0
# Configuration Options
1

2
The zod-to-json-schema library provides extensive configuration options to customize the conversion behavior, output format, and target compatibility. Options can be passed as an object to the `zodToJsonSchema` function.
3

4
## Options Interface
5

6
```typescript { .api }
7
interface Options<Target extends Targets = "jsonSchema7"> {
8
  name: string | undefined;
9
  $refStrategy: "root" | "relative" | "none" | "seen";
10
  basePath: string[];
11
  effectStrategy: "input" | "any";
12
  pipeStrategy: "input" | "output" | "all";
13
  dateStrategy: DateStrategy | DateStrategy[];
14
  mapStrategy: "entries" | "record";
15
  removeAdditionalStrategy: "passthrough" | "strict";
16
  allowedAdditionalProperties: true | undefined;
17
  rejectedAdditionalProperties: false | undefined;
18
  target: Target;
19
  strictUnions: boolean;
20
  definitionPath: string;
21
  definitions: Record<string, ZodSchema>;
22
  errorMessages: boolean;
23
  markdownDescription: boolean;
24
  patternStrategy: "escape" | "preserve";
25
  applyRegexFlags: boolean;
26
  emailStrategy: "format:email" | "format:idn-email" | "pattern:zod";
27
  base64Strategy: "format:binary" | "contentEncoding:base64" | "pattern:zod";
28
  nameStrategy: "ref" | "title";
29
  override?: OverrideCallback;
30
  postProcess?: PostProcessCallback;
31
  openAiAnyTypeName: string;
32
}
33
```
34

35
## Default Options
36

37
```typescript { .api }
38
const defaultOptions: Options = {
39
  name: undefined,
40
  $refStrategy: "root",
41
  basePath: ["#"],
42
  effectStrategy: "input",
43
  pipeStrategy: "all",
44
  dateStrategy: "format:date-time",
45
  mapStrategy: "entries",
46
  removeAdditionalStrategy: "passthrough",
47
  allowedAdditionalProperties: true,
48
  rejectedAdditionalProperties: false,
49
  definitionPath: "definitions",
50
  target: "jsonSchema7",
51
  strictUnions: false,
52
  definitions: {},
53
  errorMessages: false,
54
  markdownDescription: false,
55
  patternStrategy: "escape",
56
  applyRegexFlags: false,
57
  emailStrategy: "format:email",
58
  base64Strategy: "contentEncoding:base64",
59
  nameStrategy: "ref",
60
  openAiAnyTypeName: "OpenAiAnyType"
61
};
62
```
63

64
## Configuration Categories
65

66
### Schema Naming and Structure
67

68
#### `name: string | undefined`
69
Specifies a name for the root schema. When provided, the schema is placed in definitions and referenced with `$ref`.
70

71
```typescript
72
// Without name - inline schema
73
zodToJsonSchema(schema)
74

75
// With name - schema in definitions
76
zodToJsonSchema(schema, { name: "MySchema" })
77
zodToJsonSchema(schema, "MySchema") // shorthand
78
```
79

80
#### `nameStrategy: "ref" | "title"`
81
Controls how the schema name is used:
82
- `"ref"`: Name used for `$ref` (default)
83
- `"title"`: Name used as `title` property
84

85
#### `definitionPath: string`
86
Path where definitions are stored (default: `"definitions"`).
87

88
#### `definitions: Record<string, ZodSchema>`
89
Pre-defined schemas that can be referenced by name.
90

91
```typescript
92
zodToJsonSchema(schema, {
93
  definitions: {
94
    User: userSchema,
95
    Address: addressSchema
96
  }
97
})
98
```
99

100
### Reference Resolution
101

102
#### `$refStrategy: "root" | "relative" | "none" | "seen"`
103
Controls how schema references are handled:
104
- `"root"`: Absolute references from document root (default)
105
- `"relative"`: Relative references between schemas
106
- `"none"`: No references, inline everything
107
- `"seen"`: Convert seen schemas to any type
108

109
#### `basePath: string[]`
110
Base path for absolute references (default: `["#"]`).
111

112
### Target Format Configuration
113

114
#### `target: Targets`
115
Specifies the target JSON Schema format:
116
- `"jsonSchema7"`: JSON Schema Draft 7 (default)
117
- `"jsonSchema2019-09"`: JSON Schema Draft 2019-09
118
- `"openApi3"`: OpenAPI 3.0 compatibility
119
- `"openAi"`: OpenAI strict mode
120

121
### Date Handling
122

123
#### `dateStrategy: DateStrategy | DateStrategy[]`
124
Controls how Zod date schemas are converted:
125

126
```typescript { .api }
127
type DateStrategy = "format:date-time" | "format:date" | "string" | "integer";
128
```
129

130
- `"format:date-time"`: ISO 8601 datetime format (default)
131
- `"format:date"`: ISO 8601 date format
132
- `"string"`: Plain string type
133
- `"integer"`: Unix timestamp
134

135
```typescript
136
// Multiple strategies (union type)
137
zodToJsonSchema(schema, {
138
  dateStrategy: ["format:date-time", "integer"]
139
})
140
```
141

142
### String Pattern Handling
143

144
#### `emailStrategy: "format:email" | "format:idn-email" | "pattern:zod"`
145
Controls email validation:
146
- `"format:email"`: Standard email format (default)
147
- `"format:idn-email"`: Internationalized domain name email
148
- `"pattern:zod"`: Use Zod's email regex pattern
149

150
#### `base64Strategy: "format:binary" | "contentEncoding:base64" | "pattern:zod"`
151
Controls base64 string handling:
152
- `"format:binary"`: Binary format
153
- `"contentEncoding:base64"`: Base64 content encoding (default)
154
- `"pattern:zod"`: Use Zod's base64 pattern
155

156
#### `patternStrategy: "escape" | "preserve"`
157
Controls regex pattern handling:
158
- `"escape"`: Escape special regex characters (default)
159
- `"preserve"`: Preserve original regex patterns
160

161
#### `applyRegexFlags: boolean`
162
Whether to apply regex flags to patterns (default: `false`).
163

164
### Collection Type Handling
165

166
#### `mapStrategy: "entries" | "record"`
167
Controls how Zod maps are converted:
168
- `"entries"`: Array of key-value pair tuples (default)
169
- `"record"`: Object with string keys
170

171
### Object Property Handling
172

173
#### `removeAdditionalStrategy: "passthrough" | "strict"`
174
Controls additional properties behavior:
175
- `"passthrough"`: Allow additional properties (default)
176
- `"strict"`: Disallow additional properties
177

178
#### `allowedAdditionalProperties: true | undefined`
179
Explicitly allow additional properties.
180

181
#### `rejectedAdditionalProperties: false | undefined`
182
Explicitly reject additional properties.
183

184
### Advanced Schema Handling
185

186
#### `effectStrategy: "input" | "any"`
187
Controls how ZodEffects are handled:
188
- `"input"`: Use input schema (default)
189
- `"any"`: Convert to any type
190

191
#### `pipeStrategy: "input" | "output" | "all"`
192
Controls how ZodPipeline is handled:
193
- `"input"`: Use input schema
194
- `"output"`: Use output schema
195
- `"all"`: Include both input and output (default)
196

197
#### `strictUnions: boolean`
198
Whether to use strict union validation (default: `false`).
199

200
### Error Handling and Descriptions
201

202
#### `errorMessages: boolean`
203
Whether to include error message support (default: `false`).
204

205
#### `markdownDescription: boolean`
206
Whether to include markdown descriptions (default: `false`).
207

208
### OpenAI Specific Options
209

210
#### `openAiAnyTypeName: string`
211
Name for the any type definition in OpenAI mode (default: `"OpenAiAnyType"`).
212

213
## Helper Functions
214

215
### `getDefaultOptions`
216

217
```typescript { .api }
218
function getDefaultOptions<Target extends Targets>(
219
  options: Partial<Options<Target>> | string | undefined
220
): Options<Target>;
221
```
222

223
Merges user options with defaults. Handles string shorthand for name option.
224

225
## Usage Examples
226

227
### Basic Configuration
228

229
```typescript
230
import { zodToJsonSchema } from "zod-to-json-schema";
231

232
const jsonSchema = zodToJsonSchema(schema, {
233
  name: "MySchema",
234
  target: "jsonSchema7",
235
  $refStrategy: "root"
236
});
237
```
238

239
### OpenAI Configuration
240

241
```typescript
242
const openAiSchema = zodToJsonSchema(schema, {
243
  target: "openAi",
244
  strictUnions: true,
245
  $refStrategy: "none"
246
});
247
```
248

249
### Complex Configuration
250

251
```typescript
252
const complexSchema = zodToJsonSchema(schema, {
253
  name: "ComplexSchema",
254
  target: "jsonSchema2019-09",
255
  dateStrategy: ["format:date-time", "integer"],
256
  emailStrategy: "format:idn-email",
257
  mapStrategy: "record",
258
  removeAdditionalStrategy: "strict",
259
  errorMessages: true,
260
  markdownDescription: true,
261
  definitions: {
262
    User: userSchema,
263
    Address: addressSchema
264
  }
265
});
266
```