Schema-DTS: TypeScript Shims for Schema.org and the Semantic Web

schema-dts is a new library (and related tools) providing 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.

Motivation

I noticed while Schema.org schema has had a lot of usage throughout the web, few Schema validation tools were integrated as part of a Developer's toolchain. For example, Google's Structured Data Testing Tool remains a main resource for many in validating the correctness of hand-written Schema.org schema.

Enter TypeScript, and the ease of defining JSON schema using typings. Thanks to the JSON-LD format and the recommendation of Google and other search engines to encode structured data using JSON-LD (rather than microdata and other structured data formats), there's an opportunity to make writing structured data much easier. We can tighten the write-test-debug iteration by including the Schema.org schema we are writing against in our development toolchain.

Usage

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".

Examples

Defining Simple Properties

import {Person} from "schema-dts";

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",
    ]
};

Using 'Context'

JSON-LD requires a "@context" property to be set on the top-level JSON object, to describe the URIs represeting the types and properties being referenced. schema-dts provides the WithContext<T> type to facilitate this.

import {Organization, Thing, WithContext} from "schema-dts";

export function JsonLd<T extends Thing>(json: T): string {
    return `<script type="application/ld+json">
${JSON.stringify(json)}
</script>`;
}

export const MY_ORG = JsonLd<Organization>({
    "@context": "https://schema.org",
    "@type": "Corporation",
    "name": "Google LLC"
});