Skip to content
Switch branches/tags

Latest commit

* Tighten up regex performance in comments.ts

* Tighten regex further.

* Fix broken test

* Fix escape stripping

* Further improve stripping to handle multi-backtick escaping.

* Also strip <code> elements.

* Fix formatting.

* Fix newline regex.

Git stats


Failed to load latest commit information.

Build Status Coverage Status schema-dts npm version schema-dts-gen version


JSON-LD TypeScript types for vocabulary.

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

Example of Code Completion using schema-dts

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, without pending and other non-core layers.

Note: This is not an officially supported Google product.


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

npm install 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 In order for your object type to accept this property, you can augment it with WithContext, e.g.:

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

const p: WithContext<Person> = {
  '@context': '',
  '@type': 'Person',
  name: 'Eve',
  affiliation: {
    '@type': 'School',
    name: 'Nice School',

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': ' } 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.

import {Graph} from 'schema-dts';

const graph: Graph = {
  '@context': '',
  '@graph': [
      '@type': 'Person',
      '@id': '',
      name: 'Alyssa P. Hacker',
      hasOccupation: {
        '@type': 'Occupation',
        name: 'LISP Hacker',
        qualifications: 'Knows LISP',
      mainEntityOfPage: {'@id': ''},
      subjectOf: {'@id': ''},
      '@type': 'AboutPage',
      '@id': '',
      url: '',
      name: "Alyssa P. Hacker's Website",
      inLanguage: 'en-US',
      description: 'The personal website of LISP legend Alyssa P. Hacker',
      mainEntity: {'@id': ''},
      '@type': 'WebPage',
      '@id': '',
      url: '',
      name: "About | Alyssa P. Hacker's Website",
      inLanguage: 'en-US',
      isPartOf: {
        '@id': '',
      about: {'@id': ''},
      mainEntity: {'@id': ''},

Schema Typings Generator

The Schema Typings Generator is available in the schema-dts-gen package.

npm install schema-dts-gen
npx schema-dts-gen --ontology=

Command line usage:

  • Specify your ontology

    • Specify --ontology: An HTTPs URL to an .nt NTriple file declaring your ontology.

      Must be compatible with, including the DataTypes and specifying a top-level Thing type.

  • --context: Defaults to, the value or values to be used with the "@context" property.

    Can be either a single URL, or a comma separated list of two or more name:URL pairs.

    The context affects names of string properties in types, as well as the values of an object's "@type".

  • --deprecated/--nodeprecated: Whether or not to include deprecated types and properties. When included, these types will still be marked with @deprecated JSDOC tags.

  • --verbose: Outputs additional logs and debugging notes to stderr.


Use NPM to install dependencies:

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:

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

or simply build the schema-dts generator:

npm run build-gen

To contribute changes, see the file.