Zod to JSON Schema Converter

Common errors

• Unsupported Zod schema type or structure for conversion.

  cause Attempting to convert a Zod v4 schema that uses features not compatible with `zod-to-json-schema`'s v3 interpretation.
  fix Ensure Zod schemas are defined using v3-compatible syntax, or migrate to Zod v4's native `z.tojsonSchema()` for Zod v4 schemas.

• Generated JSON schema differs from expected output for a complex Zod type (e.g., union, intersection).

  cause `zod-to-json-schema` might interpret certain complex Zod types differently than anticipated, or may not fully support all intricate Zod features.
  fix Carefully review the `zod-to-json-schema` documentation for specific type support. Manually adjust the generated JSON schema if a Zod type's conversion is not as expected.

• JSON Schema validation error: Reference '#/definitions/...' could not be resolved.

  cause Recursive or recurring schemas require a named definition to generate correct `$ref`s, but the schema was not provided with a name.
  fix Ensure the top-level schema is provided with a `name` via the second argument to `zodToJsonSchema` (e.g., `zodToJsonSchema(mySchema, 'MySchema')`) or through the options object to enable proper `$ref` generation.

• Optional properties in Zod schema are converted to `required` and `nullable` in the JSON schema output.

  cause The 'Open AI strict mode' (or a similar configuration option) is enabled, which explicitly converts optional Zod properties to `required` and `nullable` in the resulting JSON schema.
  fix If this conversion is not desired, review the options object passed to `zodToJsonSchema` and adjust or disable any strict mode or OpenAPI compatibility settings.

Warnings

• deprecated This package is officially deprecated as of November 2025 and will no longer be actively maintained.
  Fix: Migrate your schema generation to Zod v4, which includes native JSON schema generation via `z.tojsonSchema()`.
• gotcha Although `zod-to-json-schema` v3.25+ can use Zod v4 as a peer-dependency, it only supports converting Zod schemas defined using v3-compatible syntax. It does not fully support Zod v4-specific schema features.
  Fix: If your project uses Zod v4 and you need to convert v4-style schemas, use Zod's built-in `z.tojsonSchema()` method directly. If you must use `zod-to-json-schema` with Zod v4 installed, ensure your Zod schemas are written in a v3-compatible manner.
• gotcha The library primarily targets the OpenAPI 3.0 specification for JSON schema generation. OpenAPI 3.1 supports standard JSON Schema, so direct output might not be fully compliant without adjustments.
  Fix: Be aware of the target OpenAPI version. If you require OpenAPI 3.1 compliance, carefully review the generated schema and apply any necessary post-processing or configuration adjustments.
• gotcha When 'Open AI strict mode' is enabled via options, optional object properties in Zod schemas are converted to `required` but `nullable` properties in the generated JSON schema.
  Fix: Understand this specific conversion behavior. If it does not match your desired JSON schema for optional properties, review the options passed to `zodToJsonSchema` or post-process the output.

Install

• npm install zod-to-json-schema npm
• yarn add zod-to-json-schema yarn
• pnpm add zod-to-json-schema pnpm

Imports

• z

  import { z } from 'zod';

  For Zod v3.25 and v4, you can also use `import { z } from 'zod/v3';` if you need explicit v3 types.
• zodToJsonSchema

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

Quickstart

Converts a Zod object schema into a JSON schema, demonstrating basic type conversion, property validation, and the use of a schema name for `$ref` generation.

import { z } from 'zod';
import { zodToJsonSchema } from 'zod-to-json-schema';

const mySchema = z
  .object({
    myString: z.string().min(5),
    myUnion: z.union([z.number(), z.boolean()]),
  })
  .describe('My neat object schema');

const jsonSchema = zodToJsonSchema(mySchema, 'mySchema');

console.log(JSON.stringify(jsonSchema, null, 2));
/*
Expected output:
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$ref": "#/definitions/mySchema",
  "definitions": {
    "mySchema": {
      "description": "My neat object schema",
      "type": "object",
      "properties": {
        "myString": {
          "type": "string",
          "minLength": 5
        },
        "myUnion": {
          "type": [
            "number",
            "boolean"
          ]
        }
      },
      "additionalProperties": false,
      "required": [
        "myString",
        "myUnion"
      ]
    }
  }
}
*/