schema-dts

> 编程语言

Open source

JSON-LD TypeScript types for Schema.org vocabulary

1.2K stars0 likes0 views

Website GitHub

About

JSON-LD TypeScript types for Schema.org vocabulary

schema-dts

JSON-LD TypeScript types for Schema.org vocabulary.

schema-dts provides TypeScript definitions for Schema.org vocabulary in JSON-LD format. The typings are exposed as complete sets of discriminated type unions, allowing for easy completions and stricter validation.

This repository contains two NPM packages:

schema-dts-gen Providing a command-line tool to generate TypeScript files based on a specific Schema version and layer.
schema-dts Pre-packaged TypeScript typings of latest Schema.org schema, without pending and other non-core layers.

Note: This is not an officially supported Google product.

Usage

To use the typings for your project, simply add the schema-dts NPM package to your project:

bash

npm install --save-dev schema-dts

Then you can use it by importing "schema-dts".

Root context

You will usually want your top-level item to include a @context, like https://schema.org. In order for your object type to accept this property, you can augment it with WithContext, e.g.:

typescript

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

const p: WithContext = {
  '@context': 'https://schema.org',
  '@type': 'Person',
  name: 'Eve',
  affiliation: {
    '@type': 'School',
    name: 'Nice School',
  },
};

Merging multiple concrete types

Some Schema.org objects can legitimately carry multiple concrete @type values. For those advanced cases, schema-dts exports leaf types alongside the usual union aliases, plus a MergeLeafTypes helper for combining them:

typescript

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

const product: WithContext
> = {
  '@context': 'https://schema.org',
  '@type': ['Product', 'SoftwareApplication'],
  name: 'My App',
  offers: {
    '@type': 'Offer',
    price: 89,
    priceCurrency: 'USD',
  },
  operatingSystem: 'Any',
};

MergeLeafTypes expects concrete leaf types such as ProductLeaf, not union aliases such as Product.

Implementing schema types in a class

Every Schema.org type is exported twice: as a union alias (e.g. Person, which also spans its subtypes plus an id-reference string) and as a concrete "leaf" interface (e.g. PersonLeaf) describing exactly one @type. Because the leaf interface is a plain object type, you can implements it from a class, which the union alias does not allow:

typescript

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

class Employee implements PersonLeaf {
  readonly '@type' = 'Person';
  name: string;

  constructor(name: string) {
    this.name = name;
  }
}

Reach for the leaf interface (PersonLeaf) instead of the union alias (Person) whenever you need a single, concrete object shape to implement or extend.

Graphs and IDs

JSON-LD supports '@graph' objects that have richer interconnected links between the nodes. You can do that easily in schema-dts by using the Graph type.

Notice that any node can have an @id when defining it. And you can reference the same node from different places by simply using an ID stub, for example { '@id': 'https://my.site/about/#page } below is an ID stub.

The example below shows potential JSON-LD for an About page. It includes definitions of Alyssa P. Hacker (the author & subject of the page), the specific page in this URL, and the website it belongs to. Some objects are still defined as inline nested objects (e.g. Occupation), since they are only referenced by their parent. Other objects are defined at the top-level with an @id, because multiple nodes refer to them.

…

Input and Output constraints

Actions support additional information to describe inputs and outputs, so each property can be annotated using -input and -output suffixes and you can do that in schema-dts by using the WithActionConstraints type for each action type you want to annotate. See the following examples:

typescript

import type {SearchAction, WithActionConstraints} from 'schema-dts';

const potentialAction: WithActionConstraints = {
  '@type': 'SearchAction',
  'query-input': 'required name=search_term_string',
  // ...
};

typescript

import type {SearchAction, WebSite, WithActionConstraints} from 'schema-dts';

const website: WebSite = {
  '@type': 'WebSite',
  potentialAction: {
    '@type': 'SearchAction',
    'query-input': 'required name=search_term_string',
  } as WithActionConstraints,
};

Real-world examples

Below are common patterns for using schema-dts types when building JSON-LD for real websites.

Organization and WebSite (every site should have these)

typescript

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

const org: WithContext = {
  '@context': 'https://schema.org',
  '@type': 'Organization',
  name: 'Acme Corp',
  url: 'https://acme.com',
  logo: 'https://acme.com/logo.png',
  sameAs: ['https://twitter.com/acme', 'https://www.linkedin.com/company/acme'],
};

const site: WithContext = {
  '@context': 'https://schema.org',
  '@type': 'WebSite',
  name: 'Acme Corp',
  url: 'https://acme.com',
};

Product with Offer (e-commerce)

typescript

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

const product: WithContext = {
  '@context': 'https://schema.org',
  '@type': 'Product',
  name: 'Classic Leather Wallet',
  description: 'Full-grain leather bifold wallet with RFID blocking.',
  image: 'https://shop.example/images/wallet.jpg',
  sku: 'WALLET-001',
  brand: {
    '@type': 'Brand',
    name: 'Example Shop',
  },
  offers: {
    '@type': 'Offer',
    price: 89,
    priceCurrency: 'USD',
    availability: 'https://schema.org/InStock',
    url: 'https://shop.example/products/classic-wallet',
  },
};

FAQPage (content sites)

typescript

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

const faq: WithContext = {
  '@context': 'https://schema.org',
  '@type': 'FAQPage',
  mainEntity: [
    {
      '@type': 'Question',
      name: 'Do you ship internationally?',
      acceptedAnswer: {
        '@type': 'Answer',
        text: 'Yes, we ship to over 50 countries.',
      },
    },
    {
      '@type': 'Question',
      name: 'What is your return policy?',
      acceptedAnswer: {
        '@type': 'Answer',
        text: 'We offer a 30-day return policy on all items.',
      },
    },
  ],
};

Article (blog posts)

typescript

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

const article: WithContext = {
  '@context': 'https://schema.org',
  '@type': 'Article',
  headline: 'How to choose a leather wallet',
  datePublished: '2026-03-01',
  dateModified: '2026-03-15',
  author: {
    '@type': 'Person',
    name: 'Jane Smith',
    url: 'https://blog.example/authors/jane',
  },
  image: 'https://blog.example/images/wallet-guide.jpg',
  description: 'A practical guide to choosing a leather wallet that lasts.',
};

Injecting JSON-LD into HTML

When serializing JSON-LD for injection into a `

bash


> **Tip:** See [`examples.md`](./examples.md) for more integration patterns,
> including React, Next.js, Astro, and other frameworks.

# Schema Typings Generator

The Schema Typings Generator is available in the
[**`schema-dts-gen`**](https://www.npmjs.com/package/schema-dts-gen) package.

```sh
npm install --save-dev schema-dts-gen
npx schema-dts-gen --ontology=https://schema.org/version/latest/schemaorg-all-https.nt

…

bash

sh
npm install

We have wrappers around tsc and tsc --build to build our generator other .d.ts files.

To generate TypeScript from the latest Schema.org Schema:

bash

npm run build-gen && npm run build-schema

or simply build the schema-dts generator:

bash

npm run build-gen

To contribute changes, see the CONTRIBUTING.md file.

Issues· 0 open

View all issues Open on GitHub

No open issues yet, or sync has not completed.

> Tags

TypeScriptjson-ldknowledge-graphlinked-dataontology

No comments yet. Be the first to share.

> Details

PublishedAug 1, 2026

UpdatedSep 17, 2026

Category编程语言

PricingOpen source

> Related tools

TypeScript

JavaScript 的超集，为前端与全栈提供静态类型

Python

通用编程语言，广泛用于 Web、数据与 AI

Google 推出的简洁高效系统语言

schema-dts

About

schema-dts

Usage

Root context

Merging multiple concrete types

Implementing schema types in a class

Graphs and IDs

Input and Output constraints

Real-world examples

Organization and WebSite (every site should have these)

Product with Offer (e-commerce)

FAQPage (content sites)

Article (blog posts)

Injecting JSON-LD into HTML

Issues· 0 open

> Tags

> Discussion

> Details

> Related tools