Converts Zod schemas to Json Schemas
zod-to-json-schema is a conversion utility that transforms Zod schemas into JSON Schema format, enabling interoperability between TypeScript-native validation and tooling that expects JSON Schema. With over 21 million weekly downloads, it serves as the bridge between Zod's runtime validation and systems like OpenAPI documentation generators, API validators, and AI structured output processors.
The package handles the full spectrum of Zod schema types including primitives, objects, arrays, unions, and complex nested structures. It resolves recursive schemas using JSON Schema's $ref mechanism, supports custom transformations via override and postProcess hooks, and provides specialized modes for OpenAPI 3.0 compatibility and OpenAI strict mode requirements.
While Zod 4 introduced experimental native toJSONSchema() methods, zod-to-json-schema remains relevant for projects requiring advanced customization, Zod 3 compatibility, or control over schema generation behavior. It's particularly valuable when building API documentation toolchains, integrating with schema registries, or maintaining legacy OpenAPI specifications that depend on specific JSON Schema dialects.
Developers working with microservices architectures, API-first design, or AI integration pipelines rely on this package to maintain a single source of truth for validation logic while generating portable schema definitions for documentation, client generation, and cross-language validation.
import { z } from 'zod';
import { zodToJsonSchema } from 'zod-to-json-schema';
const UserSchema = z.object({
id: z.string().uuid(),
email: z.string().email(),
age: z.number().int().min(18).optional(),
roles: z.array(z.enum(['admin', 'user', 'guest'])),
metadata: z.record(z.string(), z.any())
}).describe('User account representation');
const PostSchema = z.object({
title: z.string().min(1).max(200),
author: UserSchema,
tags: z.array(z.string()).min(1),
published: z.boolean().default(false)
});
const jsonSchema = zodToJsonSchema(PostSchema, {
name: 'Post',
target: 'openApi3',
removeAdditionalStrategy: 'strict',
override: (def, refs) => {
if (refs.currentPath.at(-1) === 'metadata') {
return { type: 'object', additionalProperties: true };
}
return undefined;
}
});
console.log(JSON.stringify(jsonSchema, null, 2));API Documentation Generation: Automatically generate OpenAPI 3.0 specification files from Zod schemas used in API route handlers, ensuring documentation stays synchronized with validation logic without manual JSON Schema authoring.
AI Structured Outputs: Convert Zod schemas to JSON Schema format required by OpenAI function calling and structured output APIs, with special handling for nullable fields and strict mode requirements that AI providers enforce.
Cross-Language Validation: Generate portable JSON Schemas from TypeScript Zod definitions to share with teams using other languages, enabling consistent validation rules across polyglot microservices without duplicating business logic.
Schema Registries: Publish JSON Schema representations of Zod types to centralized schema registries for versioning and discovery, allowing consumers to validate data against published contracts without TypeScript runtime dependencies.
Form Generation: Feed generated JSON Schemas into UI form builders that render dynamic forms from schema definitions, leveraging Zod's TypeScript-first validation while supporting JSON Schema-based form libraries.
npm install zod-to-json-schemapnpm add zod-to-json-schemabun add zod-to-json-schema