or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

core-types.mdcreative-work.mdevents.mdindex.mdperson-organization.mdplace-location.mdproducts-commerce.mdroles-relationships.mdschema-generation.md
tile.json

tessl/npm-schema-dts

TypeScript definitions and generator for Schema.org vocabulary with strongly-typed JSON-LD support

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/schema-dts@1.1.x

To install, run

npx @tessl/cli install tessl/npm-schema-dts@1.1.0

index.mddocs/

Schema-DTS

Schema-DTS is a monorepo providing two complementary packages for working with Schema.org in TypeScript:

  • schema-dts: Pre-built TypeScript definitions for Schema.org vocabulary in JSON-LD format
  • schema-dts-gen: Command-line tool and library for generating custom TypeScript definitions from any Schema.org-compatible ontology

Together, they offer strongly-typed definitions for all Schema.org types, enabling compile-time type safety and IntelliSense support for semantic web applications.

Package Information

Schema-DTS (Type Definitions)

  • Package Name: schema-dts
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install schema-dts

Schema-DTS-Gen (Generator Tool)

  • Package Name: schema-dts-gen
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install schema-dts-gen
  • CLI Usage: npx schema-dts-gen [options]

Core Imports

Schema-DTS Type Definitions

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

For CommonJS:

const { Person, Organization, WithContext, Graph, Thing } = require("schema-dts");

Schema-DTS-Gen Programmatic API

import { WriteDeclarations, loadTriples } from "schema-dts-gen";
import { Class, Property, EnumValue } from "schema-dts-gen";

For CommonJS:

const { WriteDeclarations, loadTriples } = require("schema-dts-gen");

Basic Usage

Using Schema-DTS Type Definitions

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

// Define a simple Person with type safety
const person: Person = {
  "@type": "Person",
  name: "Grace Hopper",
  disambiguatingDescription: "American computer scientist",
  birthDate: "1906-12-09",
  deathDate: "1992-01-01",
  award: [
    "Presidential Medal of Freedom",
    "National Medal of Technology and Innovation",
    "IEEE Emanuel R. Piore Award",
  ],
};

// Use WithContext for complete JSON-LD documents
const personWithContext: WithContext<Person> = {
  "@context": "https://schema.org",
  "@type": "Person",
  name: "Ada Lovelace",
  birthDate: "1815-12-10",
  deathDate: "1852-11-27",
};

Using Schema-DTS-Gen CLI

# Generate TypeScript definitions from default Schema.org
npx schema-dts-gen > schema.ts

# Generate from custom ontology with deprecated types excluded
npx schema-dts-gen --ontology=https://example.com/custom.nt --nodeprecated > custom-schema.ts

# Generate with custom JSON-LD context
npx schema-dts-gen --context="rdf:http://www.w3.org/2000/01/rdf-schema,schema:https://schema.org" > multi-context-schema.ts

Using Schema-DTS-Gen Programmatically

import { WriteDeclarations, loadTriples } from "schema-dts-gen";

// Load triples from remote ontology and generate TypeScript
const graph = await loadTriples("https://schema.org/version/latest/schemaorg-all-https.nt");
await WriteDeclarations(graph, false, context, (content) => {
  console.log(content); // Generated TypeScript definitions
});

Architecture

Schema-DTS is built around several key components across both packages:

Schema-DTS (Type Definitions)

  • Type System: Complete TypeScript definitions for all 800+ Schema.org types with proper inheritance hierarchy
  • JSON-LD Context: WithContext<T> wrapper for adding required @context properties
  • Graph Support: Graph interface for complex interconnected data structures with @id references
  • Role System: Generic Role<T, P> types for modeling relationships between entities
  • Value Constraints: Union types with Schema.org enumerated values and primitive types
  • Discriminated Unions: All Schema.org types use @type property for type discrimination

Schema-DTS-Gen (Generator)

  • RDF Processing: N3-based triple loading and processing from .nt files
  • Class Generation: Automatic TypeScript interface generation for Schema.org classes
  • Property Generation: Type-safe property definitions with proper inheritance
  • Context Management: Flexible JSON-LD context configuration and scoping
  • CLI Interface: Command-line tool with comprehensive configuration options
  • Programmatic API: Library functions for custom generation workflows

Capabilities

Schema Generation (schema-dts-gen)

Core functionality for generating TypeScript definitions from RDF ontologies.

import { Store } from "n3";

function WriteDeclarations(
  graph: Store,
  includeDeprecated: boolean,
  context: Context,
  write: (content: string) => Promise<void> | void
): Promise<void>;

function loadTriples(url: string): Promise<Store>;

class Context {
  static Parse(contextSpec: string): Context;
  getScopedName(node: NamedNode): string;
  contextProperty(): PropertySignature;
}

Schema Generation

Core JSON-LD Types

Essential types for creating valid JSON-LD documents with Schema.org vocabulary.

type WithContext<T extends Thing> = T & {
  "@context": "https://schema.org";
};

interface Graph {
  "@context": "https://schema.org";
  "@graph": readonly Thing[];
}

type Thing = ThingLeaf | Action | BioChemEntity | CreativeWork | Event | 
  Intangible | MedicalEntity | Organization | Person | Place | Product | 
  StupidType | Taxon;

Core JSON-LD Types

Person and Organization Types

Schema.org types representing people and organizations with their properties and relationships.

type Person = PersonLeaf | Patient | string;

type Organization = OrganizationLeaf | Airline | Consortium | Cooperative | 
  Corporation | EducationalOrganization | FundingScheme | GovernmentOrganization |
  LibrarySystem | LocalBusiness | MedicalOrganization | NewsMediaOrganization |
  NGO | OnlineBusiness | PerformingGroup | PoliticalParty | Project |
  ResearchOrganization | SearchRescueOrganization | SportsOrganization |
  WorkersUnion | string;

Person and Organization Types

Creative Work Types

Schema.org types for creative content including articles, books, websites, media, and software.

type CreativeWork = CreativeWorkLeaf | AmpStory | ArchiveComponent | Article |
  Atlas | Blog | Book | Certification | Chapter | Claim | Clip | Code |
  Collection | ComicStory | Comment | Conversation | Course |
  CreativeWorkSeason | CreativeWorkSeries | DataCatalog | Dataset |
  DefinedTermSet | Diet | DigitalDocument | Drawing |
  EducationalOccupationalCredential | Episode | ExercisePlan | Game |
  Guide | HowTo | HowToDirection | HowToSection | HowToStep | HowToTip |
  HyperToc | HyperTocEntry | LearningResource | Legislation | Manuscript |
  Map | MathSolver | MediaObject | MediaReviewItem | Menu | MenuSection |
  Message | Movie | MusicComposition | MusicPlaylist | MusicRecording |
  Painting | Photograph | Play | Poster | PublicationIssue |
  PublicationVolume | Quotation | Review | Sculpture | Season |
  SheetMusic | ShortStory | SoftwareApplication | SoftwareSourceCode |
  SpecialAnnouncement | Statement | Thesis | TVSeason | TVSeries |
  VisualArtwork | WebContent | WebPage | WebPageElement | WebSite;

Creative Work Types

Place and Location Types

Schema.org types for geographic locations, venues, businesses, and addresses.

type Place = PlaceLeaf | Accommodation | AdministrativeArea | CivicStructure |
  Landform | LandmarksOrHistoricalBuildings | LocalBusiness | Residence |
  TouristAttraction | TouristDestination | string;

type LocalBusiness = LocalBusinessLeaf | AnimalShelter | ArchiveOrganization |
  AutomotiveBusiness | ChildCare | Dentist | DryCleaningOrLaundry |
  EmergencyService | EmploymentAgency | EntertainmentBusiness |
  FinancialService | FoodEstablishment | GovernmentOffice |
  HealthAndBeautyBusiness | HomeAndConstructionBusiness | InternetCafe |
  LegalService | Library | LodgingBusiness | MedicalBusiness |
  ProfessionalService | RadioStation | RealEstateAgent | RecyclingCenter |
  SelfStorage | ShoppingCenter | SportsActivityLocation | Store |
  TelevisionStation | TouristInformationCenter | TravelAgency | string;

Place and Location Types

Event Types

Schema.org types for events, performances, courses, and scheduled activities.

type Event = EventLeaf | BusinessEvent | ChildrensEvent | ComedyEvent |
  CourseInstance | DanceEvent | DeliveryEvent | EducationEvent | EventSeries |
  ExhibitionEvent | Festival | FoodEvent | Hackathon | LiteraryEvent |
  MusicEvent | PublicationEvent | SaleEvent | ScreeningEvent | SocialEvent |
  SportsEvent | TheaterEvent | UserInteraction | VisualArtsEvent;

Event Types

Product and Commerce Types

Schema.org types for products, offers, orders, and e-commerce functionality.

type Product = ProductLeaf | DietarySupplement | Drug | IndividualProduct |
  ProductCollection | ProductGroup | ProductModel | SomeProducts | Vehicle;

Product and Commerce Types

Role and Relationship System

Schema.org Role types for modeling complex relationships between entities.

type Role<TContent = never, TProperty extends string = never> = 
  RoleLeaf<TContent, TProperty> | LinkRole<TContent, TProperty> |
  OrganizationRole<TContent, TProperty> | PerformanceRole<TContent, TProperty>;

type SchemaValue<T, TProperty extends string> = T | Role<T, TProperty> | 
  readonly (T | Role<T, TProperty>)[];

Role and Relationship System

Data Types

Primitive Types

Schema.org provides specific typing for common data formats.

type Boolean = "https://schema.org/False" | "False" | 
  "https://schema.org/True" | "True" | boolean;

type Date = string; // ISO 8601 date format

type DateTime = string; // ISO 8601 date and time format

type Number = Float | Integer | number | `${number}`;

type Text = CssSelectorType | PronounceableText | URL | XPathType | string;

type Time = string;

Reference Types

Types for referencing other entities in JSON-LD.

type IdReference = {
  "@id": string;
};