zod-to-json-schema

The zod-to-json-schema library converts Zod schemas into JSON schemas. It supports basic validations (string, number, array length), string patterns, and resolves recursive/recurring schemas using internal $refs.

Key features include:

• Support for legacy OpenAPI 3.0 specification.
• Support for OpenAI strict mode (replaces optional properties with required but nullable ones).
• Compatibility with Zod v4 as a peer-dependency (as of v3.25, provided you use v3-schemas).

import { z } from "zod"; // Or, using v3.25 or v4, "zod/v3"
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");

Zod's default behavior is to strip undeclared properties. To control how additionalProperties appears in the JSON Schema, use the following strategies:

1. To allow additional properties:
   • Set removeAdditionalStrategy to "strict" (this allows them for any object not explicitly marked with .strict()).
   • OR keep the default "passthrough" and add .passthrough() to your Zod object schema.
2. To remove the additionalProperties keyword entirely:
   • Set allowedAdditionalProperties to undefined (if you want it to be allowed/undefined).
   • Set rejectedAdditionalProperties to undefined (if you want it to be rejected/undefined).

Note: These options are ignored if the schema uses .catchall(...).

You can specify a name for your schema to have it placed inside a definitions object and referenced via $ref. This can be done by passing a string as the second argument to zodToJsonSchema or by using the name property in the options object.

To manually add recurring schemas into the definitions section for cleaner output, use the definitions option. This is useful for reducing redundancy in the generated JSON schema.

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

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

This package does not follow semantic versioning (SemVer).

• Major/Minor versions: These reflect feature parity with the Zod package.
• Breaking changes: API-breaking changes are kept to a minimum, but new features (like the options pattern) may be introduced in patch releases.
• Zod v4 Compatibility: While v3.25 supports Zod v4 as a peer-dependency, it does not support v4 schemas. If you need to use Zod v3 schemas, use import { z } from "zod/v3".

The override option allows you to intercept the conversion process for specific Zod types. You can provide a function that returns a custom JSON schema, undefined to let the default parser handle it, or the ignoreOverride symbol to signal that the library should decide which parser to use.

OverrideCallback signature: (def: ZodTypeDef, refs: Refs, seen: Seen | undefined, forceResolution?: boolean) => JsonSchema7Type | undefined | typeof ignoreOverride

The postProcess option allows you to run a function on the generated JSON schema after the conversion is complete. This is useful for adding metadata or transforming the structure.

PostProcessCallback signature: (jsonSchema: JsonSchema7Type | undefined, def: ZodTypeDef, refs: Refs) => JsonSchema7Type | undefined

Example: The built-in jsonDescription post-processor attempts to parse the Zod description as JSON and merge its properties into the schema.

export const jsonDescription: PostProcessCallback = (jsonSchema, def) => {
  if (def.description) {
    try {
      return {
        ...jsonSchema,
        ...JSON.parse(def.description),
      };
    } catch {}
  }

  return jsonSchema;
};

Since Zod has limited support for JSON Schema meta-keys (like examples or title), you can use the jsonDescription helper in the postProcess option.

This helper attempts to parse the Zod .describe() string as JSON and expands those keys directly into the resulting JSON Schema. This is the recommended way to add examples, title, or other custom metadata to your output.

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

const zodSchema = z.string().describe(
  JSON.stringify({
    title: "My string",
    description: "My description",
    examples: ["Foo", "Bar"],
    whatever: 123,
  }),
);

const jsonSchema = zodToJsonSchema(zodSchema, {
  postProcess: jsonDescription,
});

The postProcess callback allows you to manipulate the fully generated JSON Schema. It receives the jsonSchema, the original Zod definition, and the refs object.

Unlike override, you do not need to return a special symbol to keep the schema unchanged; simply return the jsonSchema as-is. If you return undefined, the schema will be filtered out.

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

const postProcess: PostProcessCallback = (
  jsonSchema,
  def,
  refs,
) => {
  if (!jsonSchema) {
    return jsonSchema;
  }

  // Example: Make all numbers nullable
  if ("type" in jsonSchema! && jsonSchema.type === "number") {
    jsonSchema.type = ["number", "null"];
  }

  return jsonSchema;
};

const jsonSchema = zodToJsonSchema(zodSchema, { postProcess });

To convert a Zod schema to a JSON schema, use the zodToJsonSchema function. It accepts the Zod schema as the first argument and an optional schema name as the second argument. Providing a schema name will wrap the output in a $ref pointing to a definition.

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");