0
# Schema Generation
1

2
Core functionality for generating JSON schemas from TypeScript types with extensive configuration options and advanced TypeScript feature support.
3

4
## Capabilities
5

6
### SchemaGenerator Class
7

8
Main class that orchestrates the schema generation process from TypeScript AST to JSON Schema.
9

10
```typescript { .api }
11
class SchemaGenerator {
12
  constructor(
13
    program: ts.Program,
14
    nodeParser: NodeParser,
15
    typeFormatter: TypeFormatter,
16
    config?: Config
17
  );
18
  
19
  /**
20
   * Generate schema for a specific type or all exported types
21
   * @param fullName - Type name to generate schema for, or "*" for all types
22
   * @returns Complete JSON Schema object
23
   */
24
  createSchema(fullName?: string): Schema;
25
  
26
  /**
27
   * Generate schema from specific AST nodes
28
   * @param rootNodes - Array of TypeScript AST nodes to process
29
   * @returns Complete JSON Schema object
30
   */
31
  createSchemaFromNodes(rootNodes: ts.Node[]): Schema;
32
}
33
```
34

35
**Usage Examples:**
36

37
```typescript
38
import { createGenerator } from "ts-json-schema-generator";
39

40
// Generate schema for specific type
41
const config = {
42
  path: "src/types.ts",
43
  type: "User"
44
};
45
const generator = createGenerator(config);
46
const userSchema = generator.createSchema("User");
47

48
// Generate schema for all exported types
49
const allTypesConfig = {
50
  path: "src/**/*.ts",
51
  type: "*"
52
};
53
const allSchema = createGenerator(allTypesConfig).createSchema("*");
54
```
55

56
### Factory Function
57

58
Main entry point for creating configured SchemaGenerator instances.
59

60
```typescript { .api }
61
/**
62
 * Create a fully configured SchemaGenerator instance
63
 * @param config - Configuration object for schema generation
64
 * @returns Configured SchemaGenerator instance
65
 */
66
function createGenerator(config: Config): SchemaGenerator;
67
```
68

69
### Configuration Interface
70

71
Complete configuration interface controlling all aspects of schema generation.
72

73
```typescript { .api }
74
interface Config {
75
  /** Source file path or glob pattern */
76
  path?: string;
77
  /** Type name to generate schema for, or "*" for all types */
78
  type?: string;  
79
  /** Custom TSConfig file path */
80
  tsconfig?: string;
81
  /** Control which types are included in schema */
82
  expose?: "all" | "none" | "export";
83
  /** JSDoc annotation processing level */
84
  jsDoc?: "none" | "extended" | "basic";
85
  /** Minify the generated schema */
86
  minify?: boolean;
87
  /** Sort object properties alphabetically */
88
  sortProps?: boolean;
89
  /** Enforce strict tuple types without additional items */
90
  strictTuples?: boolean;
91
  /** Skip TypeScript type checking for faster generation */
92
  skipTypeCheck?: boolean;
93
  /** Encode $ref paths for compatibility */
94
  encodeRefs?: boolean;
95
  /** Include top-level $ref definition */
96
  topRef?: boolean;
97
  /** Generate markdownDescription in addition to description */
98
  markdownDescription?: boolean;
99
  /** Additional validation keywords to include */
100
  extraTags?: string[];
101
  /** Allow additional properties for objects without index signatures */
102
  additionalProperties?: boolean;
103
  /** How to handle function types */
104
  functions?: "fail" | "comment" | "hide";
105
  /** Schema $id value */
106
  schemaId?: string;
107
  /** Discriminator handling mode */
108
  discriminatorType?: "json-schema" | "open-api";
109
}
110
```
111

112
**Configuration Examples:**
113

114
```typescript
115
// Minimal config for quick generation
116
const simpleConfig: Config = {
117
  path: "src/api.ts",
118
  type: "ApiResponse"
119
};
120

121
// Full config with all options
122
const advancedConfig: Config = {
123
  path: "src/**/*.ts",
124
  type: "*",
125
  tsconfig: "./tsconfig.json",
126
  expose: "export",
127
  jsDoc: "extended", 
128
  minify: false,
129
  sortProps: true,
130
  strictTuples: true,
131
  skipTypeCheck: false,
132
  encodeRefs: true,
133
  topRef: true,
134
  markdownDescription: true,
135
  extraTags: ["format", "pattern"],
136
  additionalProperties: false,
137
  functions: "comment",
138
  schemaId: "https://example.com/my-schema",
139
  discriminatorType: "json-schema"
140
};
141
```
142

143
### Default Configuration
144

145
Default values used when configuration options are not specified.
146

147
```typescript { .api }
148
const DEFAULT_CONFIG: Omit<Required<Config>, "path" | "type" | "schemaId" | "tsconfig"> = {
149
  expose: "export",
150
  topRef: true,
151
  jsDoc: "extended",
152
  markdownDescription: false,
153
  sortProps: true,
154
  strictTuples: false,
155
  skipTypeCheck: false,
156
  encodeRefs: true,
157
  minify: false,
158
  extraTags: [],
159
  additionalProperties: false,
160
  discriminatorType: "json-schema",
161
  functions: "comment"
162
};
163

164
type CompletedConfig = Config & typeof DEFAULT_CONFIG;
165
```
166

167
### Schema and Definition Types
168

169
Type aliases for JSON Schema structures.
170

171
```typescript { .api }
172
import type { JSONSchema7 } from "json-schema";
173

174
/** Complete JSON Schema object */
175
type Schema = JSONSchema7;
176

177
/** JSON Schema definition for types and properties */
178
type Definition = JSONSchema7;
179
```
180

181
**Generated Schema Example:**
182

183
```typescript
184
// Input TypeScript type
185
interface User {
186
  id: number;
187
  name: string;
188
  email?: string;
189
  roles: ("admin" | "user")[];
190
}
191

192
// Generated JSON Schema
193
const userSchema = {
194
  "$schema": "http://json-schema.org/draft-07/schema#",
195
  "type": "object",
196
  "properties": {
197
    "id": { "type": "number" },
198
    "name": { "type": "string" },
199
    "email": { "type": "string" },
200
    "roles": {
201
      "type": "array",
202
      "items": {
203
        "type": "string",
204
        "enum": ["admin", "user"]
205
      }
206
    }
207
  },
208
  "required": ["id", "name", "roles"],
209
  "additionalProperties": false
210
};
211
```
212

213
### Function Options
214

215
Control how function types are handled during schema generation.
216

217
```typescript { .api }
218
type FunctionOptions = "fail" | "comment" | "hide";
219
```
220

221
- **"fail"**: Throws an error when encountering function types
222
- **"comment"**: Adds a comment describing the function signature
223
- **"hide"**: Treats functions like NeverType or HiddenType (excludes from schema)