0
# Schema-DTS
1

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

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

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

9
## Package Information
10

11
### Schema-DTS (Type Definitions)
12
- **Package Name**: schema-dts
13
- **Package Type**: npm
14
- **Language**: TypeScript
15
- **Installation**: `npm install schema-dts`
16

17
### Schema-DTS-Gen (Generator Tool)
18
- **Package Name**: schema-dts-gen
19
- **Package Type**: npm
20
- **Language**: TypeScript
21
- **Installation**: `npm install schema-dts-gen`
22
- **CLI Usage**: `npx schema-dts-gen [options]`
23

24
## Core Imports
25

26
### Schema-DTS Type Definitions
27

28
```typescript
29
import type { Person, Organization, WithContext, Graph, Thing } from "schema-dts";
30
```
31

32
For CommonJS:
33

34
```javascript
35
const { Person, Organization, WithContext, Graph, Thing } = require("schema-dts");
36
```
37

38
### Schema-DTS-Gen Programmatic API
39

40
```typescript
41
import { WriteDeclarations, loadTriples } from "schema-dts-gen";
42
import { Class, Property, EnumValue } from "schema-dts-gen";
43
```
44

45
For CommonJS:
46

47
```javascript
48
const { WriteDeclarations, loadTriples } = require("schema-dts-gen");
49
```
50

51
## Basic Usage
52

53
### Using Schema-DTS Type Definitions
54

55
```typescript
56
import type { Person, WithContext } from "schema-dts";
57

58
// Define a simple Person with type safety
59
const person: Person = {
60
  "@type": "Person",
61
  name: "Grace Hopper",
62
  disambiguatingDescription: "American computer scientist",
63
  birthDate: "1906-12-09",
64
  deathDate: "1992-01-01",
65
  award: [
66
    "Presidential Medal of Freedom",
67
    "National Medal of Technology and Innovation",
68
    "IEEE Emanuel R. Piore Award",
69
  ],
70
};
71

72
// Use WithContext for complete JSON-LD documents
73
const personWithContext: WithContext<Person> = {
74
  "@context": "https://schema.org",
75
  "@type": "Person",
76
  name: "Ada Lovelace",
77
  birthDate: "1815-12-10",
78
  deathDate: "1852-11-27",
79
};
80
```
81

82
### Using Schema-DTS-Gen CLI
83

84
```bash
85
# Generate TypeScript definitions from default Schema.org
86
npx schema-dts-gen > schema.ts
87

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

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

95
### Using Schema-DTS-Gen Programmatically
96

97
```typescript
98
import { WriteDeclarations, loadTriples } from "schema-dts-gen";
99

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

107
## Architecture
108

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

111
### Schema-DTS (Type Definitions)
112
- **Type System**: Complete TypeScript definitions for all 800+ Schema.org types with proper inheritance hierarchy
113
- **JSON-LD Context**: `WithContext<T>` wrapper for adding required `@context` properties
114
- **Graph Support**: `Graph` interface for complex interconnected data structures with `@id` references
115
- **Role System**: Generic `Role<T, P>` types for modeling relationships between entities
116
- **Value Constraints**: Union types with Schema.org enumerated values and primitive types
117
- **Discriminated Unions**: All Schema.org types use `@type` property for type discrimination
118

119
### Schema-DTS-Gen (Generator)
120
- **RDF Processing**: N3-based triple loading and processing from .nt files
121
- **Class Generation**: Automatic TypeScript interface generation for Schema.org classes
122
- **Property Generation**: Type-safe property definitions with proper inheritance
123
- **Context Management**: Flexible JSON-LD context configuration and scoping
124
- **CLI Interface**: Command-line tool with comprehensive configuration options
125
- **Programmatic API**: Library functions for custom generation workflows
126

127
## Capabilities
128

129
### Schema Generation (schema-dts-gen)
130

131
Core functionality for generating TypeScript definitions from RDF ontologies.
132

133
```typescript { .api }
134
import { Store } from "n3";
135

136
function WriteDeclarations(
137
  graph: Store,
138
  includeDeprecated: boolean,
139
  context: Context,
140
  write: (content: string) => Promise<void> | void
141
): Promise<void>;
142

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

145
class Context {
146
  static Parse(contextSpec: string): Context;
147
  getScopedName(node: NamedNode): string;
148
  contextProperty(): PropertySignature;
149
}
150
```
151

152
[Schema Generation](./schema-generation.md)
153

154
### Core JSON-LD Types
155

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

158
```typescript { .api }
159
type WithContext<T extends Thing> = T & {
160
  "@context": "https://schema.org";
161
};
162

163
interface Graph {
164
  "@context": "https://schema.org";
165
  "@graph": readonly Thing[];
166
}
167

168
type Thing = ThingLeaf | Action | BioChemEntity | CreativeWork | Event | 
169
  Intangible | MedicalEntity | Organization | Person | Place | Product | 
170
  StupidType | Taxon;
171
```
172

173
[Core JSON-LD Types](./core-types.md)
174

175
### Person and Organization Types
176

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

179
```typescript { .api }
180
type Person = PersonLeaf | Patient | string;
181

182
type Organization = OrganizationLeaf | Airline | Consortium | Cooperative | 
183
  Corporation | EducationalOrganization | FundingScheme | GovernmentOrganization |
184
  LibrarySystem | LocalBusiness | MedicalOrganization | NewsMediaOrganization |
185
  NGO | OnlineBusiness | PerformingGroup | PoliticalParty | Project |
186
  ResearchOrganization | SearchRescueOrganization | SportsOrganization |
187
  WorkersUnion | string;
188
```
189

190
[Person and Organization Types](./person-organization.md)
191

192
### Creative Work Types
193

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

196
```typescript { .api }
197
type CreativeWork = CreativeWorkLeaf | AmpStory | ArchiveComponent | Article |
198
  Atlas | Blog | Book | Certification | Chapter | Claim | Clip | Code |
199
  Collection | ComicStory | Comment | Conversation | Course |
200
  CreativeWorkSeason | CreativeWorkSeries | DataCatalog | Dataset |
201
  DefinedTermSet | Diet | DigitalDocument | Drawing |
202
  EducationalOccupationalCredential | Episode | ExercisePlan | Game |
203
  Guide | HowTo | HowToDirection | HowToSection | HowToStep | HowToTip |
204
  HyperToc | HyperTocEntry | LearningResource | Legislation | Manuscript |
205
  Map | MathSolver | MediaObject | MediaReviewItem | Menu | MenuSection |
206
  Message | Movie | MusicComposition | MusicPlaylist | MusicRecording |
207
  Painting | Photograph | Play | Poster | PublicationIssue |
208
  PublicationVolume | Quotation | Review | Sculpture | Season |
209
  SheetMusic | ShortStory | SoftwareApplication | SoftwareSourceCode |
210
  SpecialAnnouncement | Statement | Thesis | TVSeason | TVSeries |
211
  VisualArtwork | WebContent | WebPage | WebPageElement | WebSite;
212
```
213

214
[Creative Work Types](./creative-work.md)
215

216
### Place and Location Types
217

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

220
```typescript { .api }
221
type Place = PlaceLeaf | Accommodation | AdministrativeArea | CivicStructure |
222
  Landform | LandmarksOrHistoricalBuildings | LocalBusiness | Residence |
223
  TouristAttraction | TouristDestination | string;
224

225
type LocalBusiness = LocalBusinessLeaf | AnimalShelter | ArchiveOrganization |
226
  AutomotiveBusiness | ChildCare | Dentist | DryCleaningOrLaundry |
227
  EmergencyService | EmploymentAgency | EntertainmentBusiness |
228
  FinancialService | FoodEstablishment | GovernmentOffice |
229
  HealthAndBeautyBusiness | HomeAndConstructionBusiness | InternetCafe |
230
  LegalService | Library | LodgingBusiness | MedicalBusiness |
231
  ProfessionalService | RadioStation | RealEstateAgent | RecyclingCenter |
232
  SelfStorage | ShoppingCenter | SportsActivityLocation | Store |
233
  TelevisionStation | TouristInformationCenter | TravelAgency | string;
234
```
235

236
[Place and Location Types](./place-location.md)
237

238
### Event Types
239

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

242
```typescript { .api }
243
type Event = EventLeaf | BusinessEvent | ChildrensEvent | ComedyEvent |
244
  CourseInstance | DanceEvent | DeliveryEvent | EducationEvent | EventSeries |
245
  ExhibitionEvent | Festival | FoodEvent | Hackathon | LiteraryEvent |
246
  MusicEvent | PublicationEvent | SaleEvent | ScreeningEvent | SocialEvent |
247
  SportsEvent | TheaterEvent | UserInteraction | VisualArtsEvent;
248
```
249

250
[Event Types](./events.md)
251

252
### Product and Commerce Types
253

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

256
```typescript { .api }
257
type Product = ProductLeaf | DietarySupplement | Drug | IndividualProduct |
258
  ProductCollection | ProductGroup | ProductModel | SomeProducts | Vehicle;
259
```
260

261
[Product and Commerce Types](./products-commerce.md)
262

263
### Role and Relationship System
264

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

267
```typescript { .api }
268
type Role<TContent = never, TProperty extends string = never> = 
269
  RoleLeaf<TContent, TProperty> | LinkRole<TContent, TProperty> |
270
  OrganizationRole<TContent, TProperty> | PerformanceRole<TContent, TProperty>;
271

272
type SchemaValue<T, TProperty extends string> = T | Role<T, TProperty> | 
273
  readonly (T | Role<T, TProperty>)[];
274
```
275

276
[Role and Relationship System](./roles-relationships.md)
277

278
## Data Types
279

280
### Primitive Types
281

282
Schema.org provides specific typing for common data formats.
283

284
```typescript { .api }
285
type Boolean = "https://schema.org/False" | "False" | 
286
  "https://schema.org/True" | "True" | boolean;
287

288
type Date = string; // ISO 8601 date format
289

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

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

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

296
type Time = string;
297
```
298

299
### Reference Types
300

301
Types for referencing other entities in JSON-LD.
302

303
```typescript { .api }
304
type IdReference = {
305
  "@id": string;
306
};
307
```