Configuration Options

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.

Options Interface

interface Options<Target extends Targets = "jsonSchema7"> {
  name: string | undefined;
  $refStrategy: "root" | "relative" | "none" | "seen";
  basePath: string[];
  effectStrategy: "input" | "any";
  pipeStrategy: "input" | "output" | "all";
  dateStrategy: DateStrategy | DateStrategy[];
  mapStrategy: "entries" | "record";
  removeAdditionalStrategy: "passthrough" | "strict";
  allowedAdditionalProperties: true | undefined;
  rejectedAdditionalProperties: false | undefined;
  target: Target;
  strictUnions: boolean;
  definitionPath: string;
  definitions: Record<string, ZodSchema>;
  errorMessages: boolean;
  markdownDescription: boolean;
  patternStrategy: "escape" | "preserve";
  applyRegexFlags: boolean;
  emailStrategy: "format:email" | "format:idn-email" | "pattern:zod";
  base64Strategy: "format:binary" | "contentEncoding:base64" | "pattern:zod";
  nameStrategy: "ref" | "title";
  override?: OverrideCallback;
  postProcess?: PostProcessCallback;
  openAiAnyTypeName: string;
}

Default Options

const defaultOptions: Options = {
  name: undefined,
  $refStrategy: "root",
  basePath: ["#"],
  effectStrategy: "input",
  pipeStrategy: "all",
  dateStrategy: "format:date-time",
  mapStrategy: "entries",
  removeAdditionalStrategy: "passthrough",
  allowedAdditionalProperties: true,
  rejectedAdditionalProperties: false,
  definitionPath: "definitions",
  target: "jsonSchema7",
  strictUnions: false,
  definitions: {},
  errorMessages: false,
  markdownDescription: false,
  patternStrategy: "escape",
  applyRegexFlags: false,
  emailStrategy: "format:email",
  base64Strategy: "contentEncoding:base64",
  nameStrategy: "ref",
  openAiAnyTypeName: "OpenAiAnyType"
};

Configuration Categories

Schema Naming and Structure

name: string | undefined

Specifies a name for the root schema. When provided, the schema is placed in definitions and referenced with $ref.

// Without name - inline schema
zodToJsonSchema(schema)

// With name - schema in definitions
zodToJsonSchema(schema, { name: "MySchema" })
zodToJsonSchema(schema, "MySchema") // shorthand

nameStrategy: "ref" | "title"

Controls how the schema name is used:

• "ref": Name used for $ref (default)
• "title": Name used as title property

definitionPath: string

Path where definitions are stored (default: "definitions").

definitions: Record<string, ZodSchema>

Pre-defined schemas that can be referenced by name.

zodToJsonSchema(schema, {
  definitions: {
    User: userSchema,
    Address: addressSchema
  }
})

Reference Resolution

$refStrategy: "root" | "relative" | "none" | "seen"

Controls how schema references are handled:

• "root": Absolute references from document root (default)
• "relative": Relative references between schemas
• "none": No references, inline everything
• "seen": Convert seen schemas to any type

basePath: string[]

Base path for absolute references (default: ["#"]).

Target Format Configuration

target: Targets

Specifies the target JSON Schema format:

• "jsonSchema7": JSON Schema Draft 7 (default)
• "jsonSchema2019-09": JSON Schema Draft 2019-09
• "openApi3": OpenAPI 3.0 compatibility
• "openAi": OpenAI strict mode

Date Handling

dateStrategy: DateStrategy | DateStrategy[]

Controls how Zod date schemas are converted:

type DateStrategy = "format:date-time" | "format:date" | "string" | "integer";

• "format:date-time": ISO 8601 datetime format (default)
• "format:date": ISO 8601 date format
• "string": Plain string type
• "integer": Unix timestamp

// Multiple strategies (union type)
zodToJsonSchema(schema, {
  dateStrategy: ["format:date-time", "integer"]
})

String Pattern Handling

emailStrategy: "format:email" | "format:idn-email" | "pattern:zod"

Controls email validation:

• "format:email": Standard email format (default)
• "format:idn-email": Internationalized domain name email
• "pattern:zod": Use Zod's email regex pattern

base64Strategy: "format:binary" | "contentEncoding:base64" | "pattern:zod"

Controls base64 string handling:

• "format:binary": Binary format
• "contentEncoding:base64": Base64 content encoding (default)
• "pattern:zod": Use Zod's base64 pattern

patternStrategy: "escape" | "preserve"

Controls regex pattern handling:

• "escape": Escape special regex characters (default)
• "preserve": Preserve original regex patterns

applyRegexFlags: boolean

Whether to apply regex flags to patterns (default: false).

Collection Type Handling

mapStrategy: "entries" | "record"

Controls how Zod maps are converted:

• "entries": Array of key-value pair tuples (default)
• "record": Object with string keys

Object Property Handling

removeAdditionalStrategy: "passthrough" | "strict"

Controls additional properties behavior:

• "passthrough": Allow additional properties (default)
• "strict": Disallow additional properties

allowedAdditionalProperties: true | undefined

Explicitly allow additional properties.

rejectedAdditionalProperties: false | undefined

Explicitly reject additional properties.

Advanced Schema Handling

effectStrategy: "input" | "any"

Controls how ZodEffects are handled:

• "input": Use input schema (default)
• "any": Convert to any type

pipeStrategy: "input" | "output" | "all"

Controls how ZodPipeline is handled:

• "input": Use input schema
• "output": Use output schema
• "all": Include both input and output (default)

strictUnions: boolean

Whether to use strict union validation (default: false).

Error Handling and Descriptions

errorMessages: boolean

Whether to include error message support (default: false).

markdownDescription: boolean

Whether to include markdown descriptions (default: false).

OpenAI Specific Options

openAiAnyTypeName: string

Name for the any type definition in OpenAI mode (default: "OpenAiAnyType").

Helper Functions

getDefaultOptions

function getDefaultOptions<Target extends Targets>(
  options: Partial<Options<Target>> | string | undefined
): Options<Target>;

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

Usage Examples

Basic Configuration

import { zodToJsonSchema } from "zod-to-json-schema";

const jsonSchema = zodToJsonSchema(schema, {
  name: "MySchema",
  target: "jsonSchema7",
  $refStrategy: "root"
});

OpenAI Configuration

const openAiSchema = zodToJsonSchema(schema, {
  target: "openAi",
  strictUnions: true,
  $refStrategy: "none"
});

Complex Configuration

const complexSchema = zodToJsonSchema(schema, {
  name: "ComplexSchema",
  target: "jsonSchema2019-09",
  dateStrategy: ["format:date-time", "integer"],
  emailStrategy: "format:idn-email",
  mapStrategy: "record",
  removeAdditionalStrategy: "strict",
  errorMessages: true,
  markdownDescription: true,
  definitions: {
    User: userSchema,
    Address: addressSchema
  }
});