schema-dts

schema-dts provides complete, discriminated-union TypeScript types for every Schema.org type, generated directly from schema.org’s own ontology. Import a type like Product or Person, annotate a JSON-LD literal with WithContext, and get full IntelliSense plus compile-time checking of property names and value shapes, instead of guessing what fields the Schema.org spec allows or silently emitting invalid structured data for SEO or knowledge-graph markup.

Because the types are generated from the canonical Schema.org RDF triples via the companion schema-dts-gen CLI, they track the vocabulary release-for-release rather than being hand-maintained, and include helpers like Graph, MergeLeafTypes, and WithActionConstraints for advanced JSON-LD patterns such as interlinked @graph documents and multi-type objects.

What You Get

• Complete Schema.org type coverage — every published Schema.org type and property, exposed as both union aliases (e.g. Person) and single-type Leaf interfaces (e.g. PersonLeaf).
• WithContext<T> helper to correctly type a JSON-LD document’s top-level @context field alongside its @type.
• Graph type for building interconnected @graph JSON-LD documents with @id-referenced nodes.
• MergeLeafTypes and WithActionConstraints helpers for multi-type objects and Schema.org Action input/output constraints.

Common Use Cases

• Adding type-checked JSON-LD structured data to a Next.js/Astro page for SEO rich results.
• Building e-commerce Product/Offer schema markup without misspelling Schema.org property names.
• Implementing a domain class that conforms to a Schema.org shape via a Leaf interface’s implements clause.
• Generating FAQPage or Article structured data for content and blog sites.

Under The Hood

Architecture The repo is an npm-workspaces monorepo of three packages — packages/schema-dts, packages/schema-dts-gen, and packages/schema-dts-lib — orchestrated from the root package.json’s workspaces field and build --workspaces script. schema-dts-gen (driven by src/cli/cli.ts and src/index.ts) reads Schema.org’s canonical NTriple ontology through src/triples/reader.ts and operators.ts, transforms the RDF triples into a class/property model in src/transform/{toClass,toProperty,toEnum,transform}.ts, then emits TypeScript source via src/ts/{class,enum,property,context,action_constraints,helper_types}.ts. The published schema-dts package contains no hand-written types at all: its build:generate script runs schema-dts-gen > lib/schema.ts and then compiles that generated file with tsc, so its entire public API is a build artifact of the generator pipeline, while schema-dts-lib supplies the small hand-written, dependency-free helper types (JsonLdObject, MergeLeafTypes) that both the generated output and consumers rely on. This generator-to-generated-output-to-thin-helpers structure means a schema.org vocabulary change propagates to the shipped .d.ts without anyone touching packages/schema-dts by hand.

Tech Stack Written entirely in TypeScript (98%+ of the codebase, ESM "type": "module") as an npm-workspaces monorepo of three packages. Build tooling is stock tsc/tsc --build plus mkdirp for output directories; tests run on Jest 30 with ts-jest, using jest.config.js’s multi-project setup (projects: ['<rootDir>/packages/*']) so each package runs its own suite. Linting is ESLint 10 (flat config) with typescript-eslint’s recommendedTypeChecked preset, eslint-plugin-jsdoc, and @stylistic/eslint-plugin, formatted with Prettier and reconciled via eslint-config-prettier; CI runs on GitHub Actions (ci.yml) alongside a CodeQL security workflow. The generator CLI itself carries no runtime dependencies beyond Node built-ins and small Markdown-parsing helpers, keeping the shipped schema-dts package’s only dependency as schema-dts-lib.

Code Quality Tests live in packages/schema-dts/test/ (easy.ts, withcontext.ts, mergeleaftypes.ts, leaf_implements.ts, withactionconstraints.ts, graph.ts, values.ts) and are exercised via tsc -p test/ — compile-time type-assertion tests rather than a runtime assertion suite, a reasonable strategy for a types-only package though it means correctness is verified by type-checking rather than by diffing generator output against a golden file (the sibling schema-dts-gen package has its own separate, more conventional test layout). The generator uses an explicit assert.ts helper and typed error paths in cli.ts/args.ts rather than silent failure. Naming is consistently PascalCase for types and camelCase for functions, and the codebase is fully type-aware-linted (ESLint’s recommendedTypeChecked) and Prettier-formatted in CI — a well-typed, lint-gated codebase, docked slightly for tests being type-check-only.

API Design The public API is deliberately minimal and idiomatic: importing a single type (import type {Person} from 'schema-dts') gets a consumer full autocomplete on every Schema.org property with zero runtime footprint, since it’s a type-only import with no bundled validation logic — a favorable DX/bundle-size tradeoff compared to packages that ship heavy runtime validators. Ergonomics are extended by the Leaf/union split (plain unions for everyday use, *Leaf interfaces when a class needs to implements a shape) and by targeted helpers (WithContext, Graph, MergeLeafTypes, WithActionConstraints) that solve real friction points in hand-writing JSON-LD, documented with runnable README examples plus a dedicated examples.md covering React/Next.js/Astro integration. Generating typings directly from an external RDF ontology and re-deriving them on every schema.org release is a fairly novel approach relative to hand-maintained @types/* packages, though the overall scope stays narrow — a typings package, not a new paradigm.