0
# Schema Generation
1

2
Core functionality for generating TypeScript definitions from RDF ontologies using schema-dts-gen. This package provides both programmatic APIs and a command-line interface for converting Schema.org or custom ontologies into strongly-typed TypeScript definitions.
3

4
## Capabilities
5

6
### WriteDeclarations Function
7

8
Main function for generating TypeScript declarations from RDF triple data.
9

10
```typescript { .api }
11
/**
12
 * Generate TypeScript declarations from RDF triple data
13
 * @param graph - N3 Store containing RDF triples
14
 * @param includeDeprecated - Whether to include deprecated classes and properties
15
 * @param context - Context object for JSON-LD context configuration
16
 * @param write - Callback function to write generated TypeScript content
17
 */
18
function WriteDeclarations(
19
  graph: Store,
20
  includeDeprecated: boolean,
21
  context: Context,
22
  write: (content: string) => Promise<void> | void
23
): Promise<void>;
24
```
25

26
**Usage Examples:**
27

28
```typescript
29
import { WriteDeclarations, loadTriples } from "schema-dts-gen";
30
import { Context } from "schema-dts-gen";
31

32
// Generate TypeScript from remote ontology
33
const graph = await loadTriples("https://schema.org/version/latest/schemaorg-all-https.nt");
34
const context = Context.Parse("https://schema.org");
35

36
await WriteDeclarations(graph, false, context, (content) => {
37
  // Write to file or stdout
38
  process.stdout.write(content);
39
});
40
```
41

42
### Triple Loading Functions
43

44
Functions for loading RDF triples from various sources.
45

46
```typescript { .api }
47
/**
48
 * Load RDF triples from a remote HTTPS URL
49
 * @param url - HTTPS URL to .nt file containing RDF triples
50
 * @returns Promise resolving to N3 Store with loaded triples
51
 */
52
function loadTriples(url: string): Promise<Store>;
53

54
/**
55
 * Load RDF triples from a local file
56
 * @param path - Local file path to .nt file
57
 * @returns Promise resolving to N3 Store with loaded triples
58
 */
59
function loadFile(path: string): Promise<Store>;
60
```
61

62
**Usage Examples:**
63

64
```typescript
65
import { loadTriples, loadFile } from "schema-dts-gen";
66

67
// Load from remote URL
68
const remoteGraph = await loadTriples("https://schema.org/version/latest/schemaorg-all-https.nt");
69

70
// Load from local file
71
const localGraph = await loadFile("./my-ontology.nt");
72
```
73

74
### Context Management
75

76
Configuration system for JSON-LD context handling.
77

78
```typescript { .api }
79
/**
80
 * Context configuration for JSON-LD generation
81
 */
82
class Context {
83
  /**
84
   * Parse context specification string into Context object
85
   * @param contextSpec - Context specification (URL or key:value pairs)
86
   */
87
  static Parse(contextSpec: string): Context;
88
  
89
  /**
90
   * Get properly scoped name for a Schema.org entity
91
   * @param node - RDF NamedNode to get scoped name for
92
   */
93
  getScopedName(node: NamedNode): string;
94
  
95
  /**
96
   * Generate @context property for TypeScript interface
97
   */
98
  contextProperty(): PropertySignature;
99
}
100
```
101

102
**Usage Examples:**
103

104
```typescript
105
import { Context } from "schema-dts-gen";
106

107
// Simple single-context
108
const simpleContext = Context.Parse("https://schema.org");
109

110
// Multi-namespace context
111
const multiContext = Context.Parse("rdf:http://www.w3.org/2000/01/rdf-schema,schema:https://schema.org");
112
```
113

114
### Command Line Interface
115

116
Schema-dts-gen provides a comprehensive CLI for generating TypeScript definitions.
117

118
```bash { .api }
119
# Basic usage
120
npx schema-dts-gen [options]
121

122
# Options:
123
--ontology <url>          # HTTPS URL to .nt file (default: Schema.org latest)
124
--file <path>             # Local .nt file path
125
--context <spec>          # JSON-LD context specification
126
--verbose / --noverbose   # Enable/disable verbose logging
127
--deprecated / --nodeprecated  # Include/exclude deprecated types
128
```
129

130
**CLI Examples:**
131

132
```bash
133
# Generate from default Schema.org ontology
134
npx schema-dts-gen > schema.ts
135

136
# Generate from custom ontology
137
npx schema-dts-gen --ontology=https://example.com/custom.nt > custom.ts
138

139
# Generate from local file with verbose output
140
npx schema-dts-gen --file=./ontology.nt --verbose > local-schema.ts
141

142
# Generate with custom context, excluding deprecated types
143
npx schema-dts-gen --context="custom:https://example.com" --nodeprecated > clean-schema.ts
144

145
# Multi-namespace context
146
npx schema-dts-gen --context="rdf:http://www.w3.org/2000/01/rdf-schema,schema:https://schema.org" > multi-ns-schema.ts
147
```
148

149
### Type System Classes
150

151
Core classes for representing Schema.org entities in the TypeScript generation process.
152

153
```typescript { .api }
154
/**
155
 * Represents a Schema.org class/type
156
 */
157
class Class {
158
  subject: string;
159
  comment: string;
160
  deprecated: boolean;
161
  supersededBy?: string;
162
  
163
  /**
164
   * Generate TypeScript interface declaration
165
   */
166
  generateInterface(): string;
167
}
168

169
/**
170
 * Represents a Schema.org property
171
 */
172
class Property {
173
  subject: string;
174
  comment: string;
175
  deprecated: boolean;
176
  supersededBy?: string;
177
  
178
  /**
179
   * Generate TypeScript property signature
180
   */
181
  generateProperty(): string;
182
}
183

184
/**
185
 * Represents a Schema.org enumeration value
186
 */
187
class EnumValue {
188
  subject: string;
189
  comment: string;
190
  
191
  /**
192
   * Generate TypeScript enum member
193
   */
194
  generateEnumMember(): string;
195
}
196
```
197

198
### Utility Functions
199

200
Helper functions for working with RDF terms and Schema.org concepts.
201

202
```typescript { .api }
203
/**
204
 * Get name from RDF term using context
205
 */
206
function nameFromContext(term: NamedNode, context: string): string | null;
207

208
/**
209
 * Get the named portion of an RDF term
210
 */
211
function namedPortion(term: NamedNode): string;
212

213
/**
214
 * Get short string representation of RDF term
215
 */
216
function shortStr(term: Term): string;
217
```
218

219
### Logging System
220

221
Configurable logging system for debugging and verbose output.
222

223
```typescript { .api }
224
/**
225
 * Configure logging options
226
 */
227
function SetOptions(options: { verbose: boolean }): void;
228

229
/**
230
 * Log a message (respects verbose setting)
231
 */
232
function Log(message: string): void;
233

234
/**
235
 * Set custom logger function
236
 * @returns Function to restore previous logger
237
 */
238
function SetLogger(newLogger: (msg: string) => void): () => void;
239
```
240

241
**Usage Examples:**
242

243
```typescript
244
import { SetOptions, Log, SetLogger } from "schema-dts-gen";
245

246
// Enable verbose logging
247
SetOptions({ verbose: true });
248

249
// Log a message
250
Log("Processing ontology...");
251

252
// Use custom logger
253
const restoreLogger = SetLogger((msg) => {
254
  console.error(`[CUSTOM] ${msg}`);
255
});
256

257
// Restore default logger
258
restoreLogger();
259
```