0
# Zod to JSON Schema
1

2
Zod to JSON Schema converts Zod schemas into JSON Schema format, enabling seamless integration between Zod's runtime validation system and JSON Schema-based tools and APIs. It supports all Zod schema types including complex ones like unions, intersections, and recursive schemas, with advanced features like reference resolution, multiple target formats, and extensive configuration options.
3

4
## Package Information
5

6
- **Package Name**: zod-to-json-schema
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install zod-to-json-schema`
10

11
## Core Imports
12

13
```typescript
14
import { zodToJsonSchema } from "zod-to-json-schema";
15
```
16

17
For default import:
18

19
```typescript
20
import zodToJsonSchema from "zod-to-json-schema";
21
```
22

23
For CommonJS:
24

25
```javascript
26
const { zodToJsonSchema } = require("zod-to-json-schema");
27
```
28

29
## Basic Usage
30

31
```typescript
32
import { z } from "zod";
33
import { zodToJsonSchema } from "zod-to-json-schema";
34

35
const mySchema = z
36
  .object({
37
    myString: z.string().min(5),
38
    myUnion: z.union([z.number(), z.boolean()]),
39
  })
40
  .describe("My neat object schema");
41

42
const jsonSchema = zodToJsonSchema(mySchema, "mySchema");
43
```
44

45
## Architecture
46

47
Zod to JSON Schema is built around several key components:
48

49
- **Core Conversion**: `zodToJsonSchema` function that orchestrates the conversion process
50
- **Parser System**: Specialized parsers for each Zod schema type (string, object, array, etc.)
51
- **Configuration System**: Extensive options for customizing output format and behavior
52
- **Reference Resolution**: Advanced system for handling circular references and reused schemas
53
- **Target Support**: Multiple output formats including JSON Schema 7, JSON Schema 2019-09, OpenAPI 3.0, and OpenAI
54

55
## Capabilities
56

57
### Schema Conversion
58

59
Core functionality for converting Zod schemas to JSON Schema format with comprehensive type support and flexible configuration.
60

61
```typescript { .api }
62
function zodToJsonSchema<Target extends Targets = "jsonSchema7">(
63
  schema: ZodSchema<any>,
64
  options?: Partial<Options<Target>> | string
65
): (Target extends "jsonSchema7" ? JsonSchema7Type : object) & {
66
  $schema?: string;
67
  definitions?: {
68
    [key: string]: Target extends "jsonSchema7"
69
      ? JsonSchema7Type
70
      : Target extends "jsonSchema2019-09"
71
        ? JsonSchema7Type
72
        : object;
73
  };
74
};
75
```
76

77
[Schema Conversion](./schema-conversion.md)
78

79
### Configuration Options
80

81
Comprehensive configuration system for customizing conversion behavior, target formats, and output structure.
82

83
```typescript { .api }
84
interface Options<Target extends Targets = "jsonSchema7"> {
85
  name: string | undefined;
86
  $refStrategy: "root" | "relative" | "none" | "seen";
87
  basePath: string[];
88
  effectStrategy: "input" | "any";
89
  pipeStrategy: "input" | "output" | "all";
90
  dateStrategy: DateStrategy | DateStrategy[];
91
  mapStrategy: "entries" | "record";
92
  removeAdditionalStrategy: "passthrough" | "strict";
93
  target: Target;
94
  strictUnions: boolean;
95
  definitionPath: string;
96
  definitions: Record<string, ZodSchema>;
97
  errorMessages: boolean;
98
  markdownDescription: boolean;
99
  patternStrategy: "escape" | "preserve";
100
  applyRegexFlags: boolean;
101
  emailStrategy: "format:email" | "format:idn-email" | "pattern:zod";
102
  base64Strategy: "format:binary" | "contentEncoding:base64" | "pattern:zod";
103
  nameStrategy: "ref" | "title";
104
  override?: OverrideCallback;
105
  postProcess?: PostProcessCallback;
106
  openAiAnyTypeName: string;
107
}
108

109
type Targets = "jsonSchema7" | "jsonSchema2019-09" | "openApi3" | "openAi";
110
type DateStrategy = "format:date-time" | "format:date" | "string" | "integer";
111
```
112

113
[Configuration Options](./configuration.md)
114

115
### Type System
116

117
Complete type definitions for JSON Schema output and configuration, enabling full TypeScript integration.
118

119
```typescript { .api }
120
type JsonSchema7Type = JsonSchema7TypeUnion & JsonSchema7Meta;
121

122
type JsonSchema7TypeUnion =
123
  | JsonSchema7StringType
124
  | JsonSchema7ArrayType
125
  | JsonSchema7NumberType
126
  | JsonSchema7BigintType
127
  | JsonSchema7BooleanType
128
  | JsonSchema7DateType
129
  | JsonSchema7EnumType
130
  | JsonSchema7LiteralType
131
  | JsonSchema7NativeEnumType
132
  | JsonSchema7NullType
133
  | JsonSchema7ObjectType
134
  | JsonSchema7RecordType
135
  | JsonSchema7TupleType
136
  | JsonSchema7UnionType
137
  | JsonSchema7UndefinedType
138
  | JsonSchema7RefType
139
  | JsonSchema7NeverType
140
  | JsonSchema7MapType
141
  | JsonSchema7AnyType
142
  | JsonSchema7NullableType
143
  | JsonSchema7AllOfType
144
  | JsonSchema7UnknownType
145
  | JsonSchema7SetType;
146
```
147

148
[Type System](./types.md)
149

150
### Advanced Features
151

152
Reference resolution, custom parsing, and post-processing capabilities for handling complex schemas and specialized requirements.
153

154
```typescript { .api }
155
type OverrideCallback = (
156
  def: ZodTypeDef,
157
  refs: Refs,
158
  seen: Seen | undefined,
159
  forceResolution?: boolean
160
) => JsonSchema7Type | undefined | typeof ignoreOverride;
161

162
type PostProcessCallback = (
163
  jsonSchema: JsonSchema7Type | undefined,
164
  def: ZodTypeDef,
165
  refs: Refs
166
) => JsonSchema7Type | undefined;
167

168
interface Refs {
169
  seen: Map<ZodTypeDef, Seen>;
170
  currentPath: string[];
171
  propertyPath: string[] | undefined;
172
  flags: { hasReferencedOpenAiAnyType: boolean };
173
}
174
```
175

176
[Advanced Features](./advanced-features.md)