Schema.org TypeScript Type Definitions

Common errors

• Type '{
      '@context': "https://schema.org";
      '@graph': ({ '@type': "Person"; '@id': string; name: string; hasOccupation: { '@type': "Occupation"; name: string; qualifications: string; }; } | { '@type': "WebPage"; '@id': string; name: string; about: { '@id': string; }; author: { '@id': string; }; dateModified: string; datePublished: string; } | { ...; })[];
  }' is not assignable to type 'WithContext<T>'.

  cause Attempting to assign a JSON-LD `@graph` object to the `WithContext<T>` type.
  fix For JSON-LD structures utilizing the `@graph` property, import and use the `Graph` type explicitly instead of `WithContext<T>`: `import type { Graph } from 'schema-dts;`.

• Declaration emit for this file requires using TypeScript version 4.1 or later. The current version is 3.9.10.

  cause Your project's TypeScript version is older than the minimum required by `schema-dts`.
  fix Update your TypeScript dependency to version 4.1.0 or higher. For example, `npm install -D typescript@latest`.

Warnings

• breaking Since `schema-dts` v0.10.0, a minimum TypeScript version of 4.1.0 is required. Older TypeScript versions will encounter compilation errors.
  Fix: Upgrade your project's TypeScript dependency to 4.1.0 or newer (e.g., `npm install typescript@latest`).
• breaking As of `schema-dts` v0.9.0, the `WithContext<T>` type can no longer represent a `Graph`. If you were using `WithContext<T>` to define a `{'@context': foo, '@graph': []}` structure, you must now explicitly import and use the `Graph` type.
  Fix: Change `WithContext<YourType>` to `Graph` when your JSON-LD object contains an `@graph` property (e.g., `import type { Graph } from 'schema-dts'; const myGraph: Graph = { ... };`).
• gotcha All imports from `schema-dts` should be type-only imports using `import type { ... } from 'schema-dts';`. While `import { ... } from 'schema-dts';` might work, it's less explicit and can potentially impact bundle size if not properly tree-shaken by your bundler.
  Fix: Consistently use `import type` for all `schema-dts` imports to clearly indicate they are only type definitions and ensure optimal bundling.
• gotcha The package is hosted under the Google GitHub organization but is explicitly stated as 'not an officially supported Google product'. While actively maintained, this might imply different support and stability guarantees compared to official Google products.
  Fix: Be aware of this distinction when considering long-term dependencies and community support for specific issues.

Install

• npm install schema-dts npm
• yarn add schema-dts yarn
• pnpm add schema-dts pnpm

Imports

• Person
  wrong:

  import { Person } from 'schema-dts';

  correct:

  import type { Person } from 'schema-dts';

  All imports are type-only for Schema.org definitions. Using 'import' without 'type' is not strictly wrong but can lead to unnecessary bundle size increases if a bundler doesn't strip it.
• WithContext
  wrong:

  const { WithContext } = require('schema-dts');

  correct:

  import type { WithContext } from 'schema-dts';

  schema-dts is an ESM-first package shipping only TypeScript types. CommonJS `require` is not supported for these type imports. Use `import type`.
• Graph

  import type { Graph } from 'schema-dts';

  Explicitly import `Graph` when defining JSON-LD with interconnected nodes using the `@graph` property. Prior to v0.9.0, `WithContext<T>` could implicitly be a `Graph`.
• MergeLeafTypes

  import type { MergeLeafTypes, ProductLeaf, SoftwareApplicationLeaf } from 'schema-dts';

  Used for combining multiple concrete Schema.org types into a single JSON-LD object. Always import with `type` and typically alongside `Leaf` types.

Quickstart

Demonstrates defining Schema.org types like `Person` and `Organization` using `WithContext<T>` and then serializing them into a JSON-LD script tag for web embedding.

import type { Person, Organization, Thing, WithContext } from 'schema-dts';

/**
 * Helper function to generate a JSON-LD script tag.
 * In a real-world app, you might use a templating engine or a UI framework component.
 */
export function generateJsonLdScript<T extends Thing>(json: WithContext<T>): string {
  return `<script type="application/ld+json">\n${JSON.stringify(json, null, 2)}\n</script>`;
}

// Define a person's structured data
const inventor: Person = {
  '@type': 'Person',
  name: 'Grace Hopper',
  disambiguatingDescription: 'American computer scientist',
  birthDate: '1906-12-09',
  deathDate: '1992-01-01',
  awards: [
    'Presidential Medal of Freedom',
    'National Medal of Technology and Innovation',
    'IEEE Emanuel R. Piore Award'
  ]
};

// Define an organization's structured data with context
const myOrganizationLd = generateJsonLdScript<Organization>({
  '@context': 'https://schema.org',
  '@type': 'Corporation',
  name: 'Example Corp LLC',
  url: 'https://www.example.com',
  logo: 'https://www.example.com/logo.png'
});

console.log(myOrganizationLd);
/* Expected output (prettified JSON):
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Corporation",
  "name": "Example Corp LLC",
  "url": "https://www.example.com",
  "logo": "https://www.example.com/logo.png"
}
</script>
*/