0
# Type System
1

2
The zod-to-json-schema library provides comprehensive TypeScript type definitions for JSON Schema output, configuration options, and internal structures. This ensures full type safety when working with the library.
3

4
## Core JSON Schema Types
5

6
### `JsonSchema7Type`
7

8
```typescript { .api }
9
type JsonSchema7Type = JsonSchema7TypeUnion & JsonSchema7Meta;
10

11
type JsonSchema7Meta = {
12
  title?: string;
13
  default?: any;
14
  description?: string;
15
  markdownDescription?: string;
16
};
17
```
18

19
The main type representing a complete JSON Schema with metadata.
20

21
### `JsonSchema7TypeUnion`
22

23
```typescript { .api }
24
type JsonSchema7TypeUnion =
25
  | JsonSchema7StringType
26
  | JsonSchema7ArrayType
27
  | JsonSchema7NumberType
28
  | JsonSchema7BigintType
29
  | JsonSchema7BooleanType
30
  | JsonSchema7DateType
31
  | JsonSchema7EnumType
32
  | JsonSchema7LiteralType
33
  | JsonSchema7NativeEnumType
34
  | JsonSchema7NullType
35
  | JsonSchema7ObjectType
36
  | JsonSchema7RecordType
37
  | JsonSchema7TupleType
38
  | JsonSchema7UnionType
39
  | JsonSchema7UndefinedType
40
  | JsonSchema7RefType
41
  | JsonSchema7NeverType
42
  | JsonSchema7MapType
43
  | JsonSchema7AnyType
44
  | JsonSchema7NullableType
45
  | JsonSchema7AllOfType
46
  | JsonSchema7UnknownType
47
  | JsonSchema7SetType;
48
```
49

50
Union of all specific JSON Schema types without metadata.
51

52
## Specific Schema Types
53

54
### String Types
55

56
```typescript { .api }
57
type JsonSchema7StringType = {
58
  type: "string";
59
  minLength?: number;
60
  maxLength?: number;
61
  format?:
62
    | "email"
63
    | "idn-email"
64
    | "uri"
65
    | "uuid"
66
    | "date-time"
67
    | "ipv4"
68
    | "ipv6"
69
    | "date"
70
    | "time"
71
    | "duration";
72
  pattern?: string;
73
  allOf?: {
74
    pattern: string;
75
    errorMessage?: ErrorMessages<{ pattern: string }>;
76
  }[];
77
  anyOf?: {
78
    format: string;
79
    errorMessage?: ErrorMessages<{ format: string }>;
80
  }[];
81
  errorMessage?: ErrorMessages<JsonSchema7StringType>;
82
  contentEncoding?: string;
83
};
84
```
85

86
### Number Types
87

88
```typescript { .api }
89
type JsonSchema7NumberType = {
90
  type: "number" | "integer";
91
  minimum?: number;
92
  maximum?: number;
93
  exclusiveMinimum?: number;
94
  exclusiveMaximum?: number;
95
  multipleOf?: number;
96
};
97

98
type JsonSchema7BigintType = {
99
  type: "integer";
100
  minimum?: number;
101
  maximum?: number;
102
  exclusiveMinimum?: number;
103
  exclusiveMaximum?: number;
104
  multipleOf?: number;
105
};
106
```
107

108
### Boolean Type
109

110
```typescript { .api }
111
type JsonSchema7BooleanType = {
112
  type: "boolean";
113
};
114
```
115

116
### Array Types
117

118
```typescript { .api }
119
type JsonSchema7ArrayType = {
120
  type: "array";
121
  items?: JsonSchema7Type;
122
  minItems?: number;
123
  maxItems?: number;
124
  uniqueItems?: boolean;
125
};
126

127
type JsonSchema7TupleType = {
128
  type: "array";
129
  items: JsonSchema7Type[];
130
  minItems?: number;
131
  maxItems?: number;
132
  additionalItems?: boolean | JsonSchema7Type;
133
};
134

135
type JsonSchema7SetType = {
136
  type: "array";
137
  items?: JsonSchema7Type;
138
  uniqueItems: true;
139
  minItems?: number;
140
  maxItems?: number;
141
};
142
```
143

144
### Object Types
145

146
```typescript { .api }
147
type JsonSchema7ObjectType = {
148
  type: "object";
149
  properties: Record<string, JsonSchema7Type>;
150
  additionalProperties?: boolean | JsonSchema7Type;
151
  required?: string[];
152
  minProperties?: number;
153
  maxProperties?: number;
154
};
155

156
type JsonSchema7RecordType = {
157
  type: "object";
158
  additionalProperties: JsonSchema7Type;
159
  minProperties?: number;
160
  maxProperties?: number;
161
};
162
```
163

164
### Union and Intersection Types
165

166
```typescript { .api }
167
type JsonSchema7UnionType = {
168
  anyOf: JsonSchema7Type[];
169
} | {
170
  type: (string | number | boolean | null)[];
171
} | {
172
  oneOf: JsonSchema7Type[];
173
};
174

175
type JsonSchema7AllOfType = {
176
  allOf: JsonSchema7Type[];
177
};
178
```
179

180
### Literal and Enum Types
181

182
```typescript { .api }
183
type JsonSchema7LiteralType = {
184
  const: any;
185
} | {
186
  type: "string" | "number" | "boolean" | "null";
187
  enum: [any];
188
};
189

190
type JsonSchema7EnumType = {
191
  type: "string";
192
  enum: string[];
193
};
194

195
type JsonSchema7NativeEnumType = {
196
  type: "string" | "number";
197
  enum: (string | number)[];
198
};
199
```
200

201
### Special Types
202

203
```typescript { .api }
204
type JsonSchema7RefType = {
205
  $ref: string;
206
};
207

208
type JsonSchema7NullType = {
209
  type: "null";
210
};
211

212
type JsonSchema7UndefinedType = {
213
  not: {};
214
} | {
215
  type: never[];
216
};
217

218
type JsonSchema7NeverType = {
219
  not: {};
220
} | {
221
  type: never[];
222
};
223

224
type JsonSchema7AnyType = {};
225

226
type JsonSchema7UnknownType = {};
227

228
type JsonSchema7NullableType = {
229
  anyOf: [JsonSchema7Type, { type: "null" }];
230
} | {
231
  type: (string | number | boolean | null)[];
232
};
233

234
type JsonSchema7DateType = {
235
  type: "string";
236
  format: "date-time" | "date";
237
} | {
238
  type: "string";
239
} | {
240
  type: "integer";
241
  minimum?: number;
242
};
243

244
type JsonSchema7MapType = {
245
  type: "array";
246
  items: {
247
    type: "array";
248
    items: [JsonSchema7Type, JsonSchema7Type];
249
    minItems: 2;
250
    maxItems: 2;
251
  };
252
} | JsonSchema7RecordType;
253
```
254

255
## Configuration Types
256

257
### `Targets`
258

259
```typescript { .api }
260
type Targets = "jsonSchema7" | "jsonSchema2019-09" | "openApi3" | "openAi";
261
```
262

263
### `DateStrategy`
264

265
```typescript { .api }
266
type DateStrategy = "format:date-time" | "format:date" | "string" | "integer";
267
```
268

269
### Callback Types
270

271
```typescript { .api }
272
type OverrideCallback = (
273
  def: ZodTypeDef,
274
  refs: Refs,
275
  seen: Seen | undefined,
276
  forceResolution?: boolean
277
) => JsonSchema7Type | undefined | typeof ignoreOverride;
278

279
type PostProcessCallback = (
280
  jsonSchema: JsonSchema7Type | undefined,
281
  def: ZodTypeDef,
282
  refs: Refs
283
) => JsonSchema7Type | undefined;
284
```
285

286
## Reference System Types
287

288
### `Refs`
289

290
```typescript { .api }
291
interface Refs {
292
  seen: Map<ZodTypeDef, Seen>;
293
  currentPath: string[];
294
  propertyPath: string[] | undefined;
295
  flags: { hasReferencedOpenAiAnyType: boolean };
296
  // Plus all Options properties
297
}
298
```
299

300
### `Seen`
301

302
```typescript { .api }
303
interface Seen {
304
  def: ZodTypeDef;
305
  path: string[];
306
  jsonSchema: JsonSchema7Type | undefined;
307
}
308
```
309

310
## Error Handling Types
311

312
### `ErrorMessages`
313

314
```typescript { .api }
315
type ErrorMessages<
316
  T extends JsonSchema7TypeUnion | { format: string } | { pattern: string },
317
  OmitProperties extends string = ""
318
> = Partial<
319
  Omit<{ [key in keyof T]: string }, OmitProperties | "type" | "errorMessages">
320
>;
321
```
322

323
## Utility Types
324

325
### `InnerDefGetter`
326

327
```typescript { .api }
328
type InnerDefGetter = () => any;
329
```
330

331
Used for lazy evaluation in recursive schema parsing.
332

333
## Constants and Symbols
334

335
### `ignoreOverride`
336

337
```typescript { .api }
338
const ignoreOverride: unique symbol;
339
```
340

341
Symbol used in override callbacks to indicate the default parser should be used.
342

343
### Built-in Post-processor
344

345
```typescript { .api }
346
const jsonDescription: PostProcessCallback;
347
```
348

349
Built-in post-processor that parses JSON from Zod schema descriptions.
350

351
## Type Guards and Utilities
352

353
### Pattern Definitions
354

355
```typescript { .api }
356
const zodPatterns: {
357
  cuid: RegExp;
358
  cuid2: RegExp;
359
  ulid: RegExp;
360
  email: RegExp;
361
  emoji: () => RegExp;
362
  uuid: RegExp;
363
  ipv4: RegExp;
364
  ipv4Cidr: RegExp;
365
  ipv6: RegExp;
366
  ipv6Cidr: RegExp;
367
  base64: RegExp;
368
  base64url: RegExp;
369
  nanoid: RegExp;
370
  jwt: RegExp;
371
};
372
```
373

374
Pre-defined regex patterns for common string validations.
375

376
## Usage with TypeScript
377

378
The type system enables full TypeScript integration:
379

380
```typescript
381
import { zodToJsonSchema, JsonSchema7Type, Options } from "zod-to-json-schema";
382

383
// Type-safe options
384
const options: Options<"jsonSchema7"> = {
385
  name: "UserSchema",
386
  target: "jsonSchema7",
387
  dateStrategy: "format:date-time"
388
};
389

390
// Type-safe result
391
const result: JsonSchema7Type & { $schema?: string } = zodToJsonSchema(schema, options);
392

393
// Custom override with proper typing
394
const customOverride: OverrideCallback = (def, refs, seen, forceResolution) => {
395
  if (def.typeName === "ZodString") {
396
    return { type: "string", format: "custom" };
397
  }
398
  return ignoreOverride;
399
};
400
```