Schema.org Type Toolkit

Documentation · GitHub

A generated toolkit for working with the Schema.org vocabulary. It bundles typed class definitions, property validators, and helpers for building and validating JSON-LD payloads without losing tree-shaking or TypeScript safety.

Features

• Typed interfaces for every Schema.org rdfs:Class
• Diagnostics-first validators that return structured Diagnostic[] objects
• Branded runtime types (for example URL, Text) for precise validation
• On-demand validators with granular static and dynamic imports
• Generated creator helpers that apply @context, @type, and default scaffolding
• Build artifacts optimised for tree-shaking; import only what you actually need

Documentation

• Documentation website
• Getting Started
• Generator Architecture
• Development Workflow
• Validation & Diagnostics
• Presets: Overview · Types · Optimizations

Installation

pnpm add @avensio/jsonld-schema
# or
npm install @avensio/jsonld-schema

The package is published as modular ESM with TypeScript declarations. The generated files use platform-neutral APIs and work in modern Node.js and browser projects.

Project Layout

| Directory | Purpose | |-----------|---------| | src/generator/ | Schema generation scripts and utilities | | src/schema/ | Generated sources: classes, creators, validation modules, raw data | | src/index.ts | Entry point exposing generated exports | | dist/ | Compiled distribution output (never edit by hand) | | test/ | Vitest suites that mirror the public API surface |

Usage

Static import (tree-shaking friendly)

import { validateOrder } from '@avensio/jsonld-schema/validation/classes/Order.validator'
import type { Order } from '@avensio/jsonld-schema/classes/Order'

const order: Order = {
  '@context': 'https://schema.org',
  '@type': 'Order',
  name: 'Example order'
}

const diagnostics = await validateOrder(order)
console.log(diagnostics)

Dynamic import (tooling, CLI, SSR)

const { validateOrder } = await import('@avensio/jsonld-schema/validation/classes/Order.validator')
const diagnostics = await validateOrder({ '@type': 'Order' })

Dynamic imports keep initial bundles minimal and pull validators only when they are used.

Validation philosophy

Validators return Diagnostic[] rather than booleans so that tooling can explain every issue at once. Each diagnostic contains an identifier, path, severity, and helpful message. TypeScript types remain untouched, keeping runtime validation separate from compile time expectations.

Branded primitive types enrich values such as URL or Number with runtime metadata, allowing validators to distinguish between string values that look like URLs and those that do not.

Package exports

{
  ".": "./dist/index.js",
  "./classes/*": "./dist/classes/*.d.ts",
  "./creators": "./dist/classes/creators.js",
  "./validation/classes/*": "./dist/validation/classes/*.js",
  "./validation/properties/*": "./dist/validation/properties/*.js",
  "./presets/types/*": "./dist/presets/types/*.json"
}

Internal maps reside in dist/validation/*.map.js for tooling that needs lookup tables.

Schema coverage snapshot

| Group | Count | |-------|-------| | rdfs:Class | 1001 | | Non rdfs:Class nodes | 537 | | Properties | 1684 | | Datatypes | 13 | | Total | 3235 |

The numbers reflect the Schema.org data snapshot bundled in src/schema/data/ and will change when the generator fetches fresh vocabulary data.

Contributing

Please read CONTRIBUTING.md for development setup, coding standards, and review expectations. Regenerate the schema (pnpm run generate:schema) and run the full test suite (pnpm test) before opening a pull request.

License

Released under the MIT License

Licensing Note for Schema Data

This package build includes code licensed under the repository's software license (MIT) and also schema data derived from Schema.org.

• Schema.org Terms: https://schema.org/docs/terms.html
• Upstream license for schema and related schema content: CC BY-SA 3.0
• License URL: https://creativecommons.org/licenses/by-sa/3.0/

See THIRD_PARTY_LICENSES.md for details.