zod-to-json-schema

Zod to Json Schema

Notice of deprecation

As of November 2025, this project will no longer be actively maintained. Zod v4 natively supports generating JSON schemas, so I recommend you switch to the new major.

Thank you to all the contributors and sponsors throughout the years! So long, and thanks for all the fish.

Summary

Does what it says on the tin; converts Zod schemas into JSON schemas!

• Supports all relevant schema types, basic string, number and array length validations and string patterns.
• Resolves recursive and recurring schemas with internal $refs.
• Supports targeting legacy Open API 3.0 specification (3.1 supports regular Json Schema).
• Supports Open AI strict mode schemas (Optional object properties are replaced with required but nullable ones).
• As of v3.25 you can use Zod v4 as a peer-dependency, so long as you still provide v3-schemas.

Looking for the exact opposite? Check out json-schema-to-zod

Sponsors

As this project will no longer be receiving updates I am no longer accepting new partnerships. Huge shout-out to CodeRabbit for keeping it real to the end | See separate section below | | errorMessages?: boolean | Include custom error messages created via chained function checks for supported zod types. See section below | | markdownDescription?: boolean | Copies the description meta to markdownDescription | | patternStrategy?: "escape" | "preserve" | The Zod string validations .includes(), .startsWith(), and .endsWith() must be converted to regex to be compatible with JSON Schema's pattern. For safety, all non-alphanumeric characters are escaped by default (consider z.string().includes(".")), but this can occasionally cause problems with Unicode-flagged regex parsers. Use preserve to prevent this escaping behaviour and preserve the exact string written, even if it results in an inaccurate regex. | | applyRegexFlags?: boolean | JSON Schema's pattern doesn't support RegExp flags, but Zod's z.string().regex() does. When this option is true (default false), a best-effort is made to transform regexes into a flag-independent form (e.g. /x/i => /[xX]/ ). Supported flags: i (basic Latin only), m, s. | | pipeStrategy?: "all" | "input" | "output" | Decide which types should be included when using z.pipe, for example z.string().pipe(z.number()) would return both string and number by default, only string for "input" and only number for "output". | | removeAdditionalStrategy?: "passthrough" | "strict" | Decide when additionalProperties should be allowed. See the section on additional properties for details. | | allowedAdditionalProperties?: true | undefined | What value to give additionalProperties when allowed. See the section on additional properties for details. | | rejectedAdditionalProperties?: false | undefined | What value to give additionalProperties when rejected. See the section on additional properties for details. | | override?: callback | See section | | postProcess?: callback | See section | | openAiAnyTypeName?: string | Decides the name of a Json schema used to allow semi-arbitrary values in Open AI structured output. If any value in the Zod-schema resolves to any "any"-type schema it will reference a definition of this name. If no such definition is provided a default Json schema will be used. Defaults to "OpenAiAnyType" |

Definitions

The definitions option lets you manually add recurring schemas into definitions for cleaner outputs. It's fully compatible with named schemas, changed definitions path and base path. Here's a simple example:

const myRecurringSchema = z.string();
const myObjectSchema = z.object({ a: myRecurringSchema, b: myRecurringSchema });

const myJsonSchema = zodToJsonSchema(myObjectSchema, {
  definitions: { myRecurringSchema },
});

Result

{
  "type": "object",
  "properties": {
    "a": {
      "$ref": "#/definitions/myRecurringSchema"
    },
    "b": {
      "$ref": "#/definitions/myRecurringSchema"
    }
  },
  "definitions": {
    "myRecurringSchema": {
      "type": "string"
    }
  }
}

Error Messages

This feature allows optionally including error messages created via chained function calls for supported zod types:

// string schema with additional chained function call checks
const EmailSchema = z.string().email("Invalid email").min(5, "Too short");

const jsonSchema = zodToJsonSchema(EmailSchema, { errorMessages: true });

Result

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "string",
  "format": "email",
  "minLength": 5,
  "errorMessage": {
    "format": "Invalid email",
    "minLength": "Too short"
  }
}

This allows for field specific, validation step specific error messages which can be useful for building forms and such. This format is accepted by react-hook-form's ajv resolver (and therefor ajv-errors which it uses under the hood). Note that if using AJV with this format will require enabling ajv-errors as vanilla AJV does not accept thi