{"id":10434,"library":"zod-to-json-schema","title":"Zod to JSON Schema Converter","description":"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.","status":"deprecated","version":"3.25.2","language":"javascript","source_language":"en","source_url":"https://github.com/StefanTerdell/zod-to-json-schema","tags":["javascript","zod","json","schema","open","api","conversion","typescript"],"install":[{"cmd":"npm install zod-to-json-schema","lang":"bash","label":"npm"},{"cmd":"yarn add zod-to-json-schema","lang":"bash","label":"yarn"},{"cmd":"pnpm add zod-to-json-schema","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for defining schemas to be converted.","package":"zod","optional":false}],"imports":[{"note":"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.","wrong":"const { zodToJsonSchema } = require('zod-to-json-schema');","symbol":"zodToJsonSchema","correct":"import { zodToJsonSchema } from 'zod-to-json-schema';"},{"note":"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.","wrong":"import * as z from 'zod/v3';","symbol":"z","correct":"import { z } from 'zod';"},{"note":"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.","symbol":"Options","correct":"import type { Options } from 'zod-to-json-schema';"}],"quickstart":{"code":"import { z } from \"zod\";\nimport { zodToJsonSchema } from \"zod-to-json-schema\";\n\nconst mySchema = z\n  .object({\n    myString: z.string().min(5),\n    myUnion: z.union([z.number(), z.boolean()]),\n    myOptional: z.string().optional(),\n    myNullable: z.boolean().nullable()\n  })\n  .describe(\"My neat object schema with various types\");\n\nconst jsonSchema = zodToJsonSchema(mySchema, {\n  name: \"mySchema\",\n  target: \"jsonSchema7\", // Explicitly target Draft 07\n  removeAdditionalStrategy: \"strict\" // Ensure additional properties are not allowed by default\n});\n\nconsole.log(JSON.stringify(jsonSchema, null, 2));\n\n/*\nExpected output (simplified):\n{\n  \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n  \"$ref\": \"#/definitions/mySchema\",\n  \"definitions\": {\n    \"mySchema\": {\n      \"description\": \"My neat object schema with various types\",\n      \"type\": \"object\",\n      \"properties\": {\n        \"myString\": {\n          \"type\": \"string\",\n          \"minLength\": 5\n        },\n        \"myUnion\": {\n          \"type\": [\n            \"number\",\n            \"boolean\"\n          ]\n        },\n        \"myOptional\": {\n          \"type\": \"string\"\n        },\n        \"myNullable\": {\n          \"type\": [\n            \"boolean\",\n            \"null\"\n          ]\n        }\n      },\n      \"additionalProperties\": false,\n      \"required\": [\n        \"myString\",\n        \"myUnion\"\n      ]\n    }\n  }\n}\n*/","lang":"typescript","description":"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."},"warnings":[{"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.","message":"This 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.","severity":"breaking","affected_versions":">=3.25.2"},{"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.","message":"While `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.","severity":"gotcha","affected_versions":">=3.25.0"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":">=3.0.0"},{"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.","message":"When 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.","severity":"gotcha","affected_versions":">=3.0.0"}],"env_vars":null,"search_vec":"'2025':69 '3.0':36 '3.25.2':49 'activ':71 'advis':88 'api':136 'built':96 'built-in':95 'cadenc':56 'ceas':73 'convers':125,137 'convert':5,17 'current':46 'depend':112 'deprec':65 'design':15 'due':74 'enabl':39 'expect':118 'featur':25 'function':99 'generat':84 'howev':61 'javascript':131 'json':3,9,21,82,104,133 'librari':14,44 'like':26 'mainten':72 'make':126 'migrat':90 'minor':59 'mode':42 'nativ':79 'novemb':68 'offici':64 'open':135 'openapi':35,40 'peer':111 'primarili':117 'recent':58 'recur':32 'recurs':30 'ref':27 'releas':55 'resolut':28 'schema':4,10,19,22,33,83,105,123,134 'seen':52 'sinc':113 'solut':130 'specif':37 'steadi':54 'still':116 'strict':41 'strong':87 'style':122 'support':23,80,106 'target':34 'transit':129 'typescript':138 'updat':60 'user':85 'util':13 'v3':121 'v3-style':120 'v3.25':114 'v4':77,93,108 'various':24 'version':48 'z.tojsonschema':98 'zod':1,7,18,76,92,102,107,119,132 'zod-to-json-schema':6,101","created_at":"2026-04-18T08:58:48.427439+00:00","updated_at":"2026-04-19T05:55:14.221631+00:00","problems":[{"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.","cause":"The package `zod-to-json-schema` is not installed or incorrectly referenced in your project.","error":"Error: Cannot find module 'zod-to-json-schema'"},{"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.","cause":"Attempting to use `zodToJsonSchema` with a CommonJS `require` statement for a potentially ESM-first context, or incorrect named import.","error":"TypeError: zodToJsonSchema is not a function"},{"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.","cause":"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.","error":"Error: Zod schemas from incompatible versions are being used."}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/StefanTerdell/zod-to-json-schema","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/zod-to-json-schema","openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization","data"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}