Registry / serialization / zod-to-json-schema

zod-to-json-schema

library3.25.2jsnpmunverified

zod-to-json-schema is a utility library designed to convert Zod schemas into JSON schemas, supporting various features like `$ref` resolution for recursive and recurring schemas, targeting OpenAPI 3.0 specifications, and enabling OpenAPI strict mode. The library is currently at version 3.25.2 and has seen a steady release cadence with recent minor updates. However, it is officially deprecated as of November 2025, with active maintenance ceasing due to Zod v4's native support for JSON schema generation. Users are strongly advised to migrate to Zod v4's built-in `z.toJSONSchema()` function. While `zod-to-json-schema` supports Zod v4 as a peer dependency since v3.25, it still primarily expects Zod v3-style schemas for conversion, making it a transitional solution.

serialization data

npm install zod-to-json-schema

github ↗package ↗

INSTALL

IMPORT

SIG · ZOD-TO-JSON-SCHEMA

zod-to-json-schema

serializationjavascriptv3.25.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

zodToJsonSchema

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

✗ const { zodToJsonSchema } = require('zod-to-json-schema');

While CommonJS `require` might work in some setups (it ships CJS and ESM builds), ES module `import` is the recommended and idiomatic way for modern JavaScript/TypeScript projects.

✓ import { z } from 'zod';

✗ import * as z from 'zod/v3';

The README mentions `import { z } from 'zod/v3'` as an option when using Zod v3.25 or v4, which implies that direct `import { z } from 'zod'` might resolve to Zod v4 if installed directly, leading to potential version conflicts if not handled carefully.

Options

✓ import type { Options } from 'zod-to-json-schema';

Import types explicitly for use in TypeScript for stricter type checking without bundling runtime code. The `Options` interface defines the configuration for the `zodToJsonSchema` function.

This quickstart demonstrates converting a Zod object schema with various types (string, union, optional, nullable) into a JSON schema, explicitly naming the schema and setting the target JSON schema draft version and `additionalProperties` behavior.

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()]), myOptional: z.string().optional(), myNullable: z.boolean().nullable() }) .describe("My neat object schema with various types"); const jsonSchema = zodToJsonSchema(mySchema, { name: "mySchema", target: "jsonSchema7", // Explicitly target Draft 07 removeAdditionalStrategy: "strict" // Ensure additional properties are not allowed by default }); console.log(JSON.stringify(jsonSchema, null, 2)); /* Expected output (simplified): { "$schema": "http://json-schema.org/draft-07/schema#", "$ref": "#/definitions/mySchema", "definitions": { "mySchema": { "description": "My neat object schema with various types", "type": "object", "properties": { "myString": { "type": "string", "minLength": 5 }, "myUnion": { "type": [ "number", "boolean" ] }, "myOptional": { "type": "string" }, "myNullable": { "type": [ "boolean", "null" ] } }, "additionalProperties": false, "required": [ "myString", "myUnion" ] } } } */

Debug

Known issues

breakingThis library is officially deprecated as of November 2025 and will no longer be actively maintained. The recommended migration path is to switch to Zod v4's native `z.toJSONSchema()` function, which provides built-in JSON schema conversion.

fix

Migrate Zod schemas to use Zod v4's native `.toJSONSchema()` method. Ensure your Zod version is `^4` and update conversion logic accordingly. Refer to Zod v4 documentation for details on its native JSON Schema conversion.

affects: >=3.25.2

gotchaWhile `zod-to-json-schema` v3.25 and later supports Zod v4 as a peer dependency, the library is primarily designed for Zod v3 schemas. It expects Zod v3-like schema structures, which might lead to unexpected behavior or incomplete conversions if using advanced Zod v4 features that differ significantly.

fix

If staying on `zod-to-json-schema` temporarily, ensure your Zod schemas are compatible with Zod v3 patterns. If using Zod v4 features, consider migrating to Zod v4's native JSON Schema conversion instead of relying on this library.

affects: >=3.25.0

gotchaThe library defaults `additionalProperties` to `false` for object schemas to align with Zod's default behavior of stripping undeclared properties during parsing. This can be surprising if explicit `additionalProperties: true` is expected without using `.passthrough()` on your Zod schema.

fix

If you intend to allow additional properties, explicitly set the `removeAdditionalStrategy` option to `'strict'` or add `.passthrough()` to your Zod object schemas. Conversely, if you want to strictly disallow them, `.strict()` on the Zod schema or `removeAdditionalStrategy: 'false'` can be used.

affects: >=3.0.0

gotchaWhen using `Open AI strict mode schemas`, optional object properties are replaced with required but nullable ones in the generated JSON Schema. This is a specific transformation for compatibility with certain API specifications and may not be desirable for general JSON Schema use cases.

fix

Be aware of this specific behavior if you enable Open AI strict mode. If this transformation is not desired, ensure Open AI strict mode is disabled in the `zodToJsonSchema` options or manually adjust the resulting schema.

affects: >=3.0.0

Errors

Common errors & fixes

Error: Cannot find module 'zod-to-json-schema'

The package `zod-to-json-schema` is not installed or incorrectly referenced in your project.

fix

Ensure the package is installed: `npm install zod-to-json-schema` or `yarn add zod-to-json-schema`. Verify the import path in your code.

TypeError: zodToJsonSchema is not a function

Attempting to use `zodToJsonSchema` with a CommonJS `require` statement for a potentially ESM-first context, or incorrect named import.

fix

Use ES module syntax: `import { zodToJsonSchema } from 'zod-to-json-schema';`. If in a CommonJS environment, check package.json `exports` or ensure your build system handles interoperability correctly. Note that `zod-to-json-schema` does ship CommonJS builds.

Error: Zod schemas from incompatible versions are being used.

Mismatch between the Zod version used to create schemas and the version `zod-to-json-schema` expects, or issues with Zod v4 compatibility when schemas aren't v3-compatible.

fix

Ensure your `zod` peer dependency is within the `^3.25.28 || ^4` range. If using Zod v4, ensure you are still providing schemas that are compatible with the expectations of `zod-to-json-schema` (primarily Zod v3-style) or consider migrating to Zod v4's native JSON schema conversion.

Upgrade

Version history

3.25.2latest on npm

Audit

Dependencies

zodrequiredPeer dependency for defining schemas to be converted.

Agent activity

65 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/StefanTerdell/zod-to-json-schema ↗

packagehttps://www.npmjs.com/package/zod-to-json-schema ↗