{"id":11985,"library":"schema-dts","title":"Schema.org TypeScript Type Definitions","description":"schema-dts provides comprehensive TypeScript definitions for the Schema.org vocabulary, specifically designed for use with JSON-LD structured data. It aims to simplify the creation and validation of Schema.org markup by offering complete sets of discriminated type unions, enabling robust type-checking and IDE auto-completion. The package is currently at version 2.0.0 and frequently updates its typings to align with the latest Schema.org releases, such as v30, v28, v15, ensuring developers always have access to current definitions. A key differentiator is its strict type validation, which helps prevent common errors in JSON-LD implementation. Although hosted under the Google GitHub organization, the README clarifies it is not an officially supported Google product, but it is actively maintained.","status":"active","version":"2.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/google/schema-dts","tags":["javascript","typescript","tsd","dts","schema.org","Semantic Web","semantic-web","Linked Data","linked-data"],"install":[{"cmd":"npm install schema-dts","lang":"bash","label":"npm"},{"cmd":"yarn add schema-dts","lang":"bash","label":"yarn"},{"cmd":"pnpm add schema-dts","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import { Person } from 'schema-dts';","symbol":"Person","correct":"import type { Person } from 'schema-dts';"},{"note":"schema-dts is an ESM-first package shipping only TypeScript types. CommonJS `require` is not supported for these type imports. Use `import type`.","wrong":"const { WithContext } = require('schema-dts');","symbol":"WithContext","correct":"import type { WithContext } from 'schema-dts';"},{"note":"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`.","symbol":"Graph","correct":"import type { Graph } from 'schema-dts';"},{"note":"Used for combining multiple concrete Schema.org types into a single JSON-LD object. Always import with `type` and typically alongside `Leaf` types.","symbol":"MergeLeafTypes","correct":"import type { MergeLeafTypes, ProductLeaf, SoftwareApplicationLeaf } from 'schema-dts';"}],"quickstart":{"code":"import type { Person, Organization, Thing, WithContext } from 'schema-dts';\n\n/**\n * Helper function to generate a JSON-LD script tag.\n * In a real-world app, you might use a templating engine or a UI framework component.\n */\nexport function generateJsonLdScript<T extends Thing>(json: WithContext<T>): string {\n  return `<script type=\"application/ld+json\">\\n${JSON.stringify(json, null, 2)}\\n</script>`;\n}\n\n// Define a person's structured data\nconst inventor: Person = {\n  '@type': 'Person',\n  name: 'Grace Hopper',\n  disambiguatingDescription: 'American computer scientist',\n  birthDate: '1906-12-09',\n  deathDate: '1992-01-01',\n  awards: [\n    'Presidential Medal of Freedom',\n    'National Medal of Technology and Innovation',\n    'IEEE Emanuel R. Piore Award'\n  ]\n};\n\n// Define an organization's structured data with context\nconst myOrganizationLd = generateJsonLdScript<Organization>({\n  '@context': 'https://schema.org',\n  '@type': 'Corporation',\n  name: 'Example Corp LLC',\n  url: 'https://www.example.com',\n  logo: 'https://www.example.com/logo.png'\n});\n\nconsole.log(myOrganizationLd);\n/* Expected output (prettified JSON):\n<script type=\"application/ld+json\">\n{\n  \"@context\": \"https://schema.org\",\n  \"@type\": \"Corporation\",\n  \"name\": \"Example Corp LLC\",\n  \"url\": \"https://www.example.com\",\n  \"logo\": \"https://www.example.com/logo.png\"\n}\n</script>\n*/","lang":"typescript","description":"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."},"warnings":[{"fix":"Upgrade your project's TypeScript dependency to 4.1.0 or newer (e.g., `npm install typescript@latest`).","message":"Since `schema-dts` v0.10.0, a minimum TypeScript version of 4.1.0 is required. Older TypeScript versions will encounter compilation errors.","severity":"breaking","affected_versions":">=0.10.0"},{"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 = { ... };`).","message":"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.","severity":"breaking","affected_versions":">=0.9.0"},{"fix":"Consistently use `import type` for all `schema-dts` imports to clearly indicate they are only type definitions and ensure optimal bundling.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Be aware of this distinction when considering long-term dependencies and community support for specific issues.","message":"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.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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;`.","cause":"Attempting to assign a JSON-LD `@graph` object to the `WithContext<T>` type.","error":"Type '{\n    '@context': \"https://schema.org\";\n    '@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; } | { ...; })[];\n}' is not assignable to type 'WithContext<T>'."},{"fix":"Update your TypeScript dependency to version 4.1.0 or higher. For example, `npm install -D typescript@latest`.","cause":"Your project's TypeScript version is older than the minimum required by `schema-dts`.","error":"Declaration emit for this file requires using TypeScript version 4.1 or later. The current version is 3.9.10."}],"ecosystem":"npm"}