zod-to-json-schema

What is zod-to-json-schema?

The zod-to-json-schema npm package is a utility that converts Zod schemas to JSON Schema. This is useful for generating JSON Schema definitions from Zod validation schemas, which can then be used for various purposes such as API documentation, validation, and more.

What are zod-to-json-schema's main functionalities?

Basic Schema Conversion

This feature allows you to convert a basic Zod schema to a JSON Schema. The example demonstrates converting a Zod object schema with string and integer properties to its JSON Schema equivalent.

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

const schema = z.object({
  name: z.string(),
  age: z.number().int(),
});

const jsonSchema = zodToJsonSchema(schema);
console.log(JSON.stringify(jsonSchema, null, 2));

Nested Schema Conversion

This feature supports the conversion of nested Zod schemas to JSON Schema. The example shows a user schema that includes an address schema, demonstrating how nested objects are handled.

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

const addressSchema = z.object({
  street: z.string(),
  city: z.string(),
});

const userSchema = z.object({
  name: z.string(),
  address: addressSchema,
});

const jsonSchema = zodToJsonSchema(userSchema);
console.log(JSON.stringify(jsonSchema, null, 2));

Array Schema Conversion

This feature allows for the conversion of Zod schemas that include arrays to JSON Schema. The example demonstrates converting a schema with an array of strings.

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

const schema = z.object({
  tags: z.array(z.string()),
});

const jsonSchema = zodToJsonSchema(schema);
console.log(JSON.stringify(jsonSchema, null, 2));

Other packages similar to zod-to-json-schema

ajv

AJV (Another JSON Schema Validator) is a popular JSON Schema validator. While it focuses on validating JSON data against JSON Schema, it also provides utilities for generating JSON Schema from various sources. Compared to zod-to-json-schema, AJV is more focused on validation rather than schema conversion.

json-schema-to-typescript

This package converts JSON Schema to TypeScript types. While it operates in the opposite direction of zod-to-json-schema, it serves a similar purpose of bridging the gap between JSON Schema and TypeScript. It is useful for generating TypeScript definitions from existing JSON Schemas.

typescript-json-schema

This package generates JSON Schema from TypeScript types. It is similar to zod-to-json-schema in that it converts type definitions to JSON Schema, but it works directly with TypeScript types instead of Zod schemas.

README

Zod to Json Schema

Summary

Does what it says on the tin; converts Zod schemas to JSON Schemas! Supports all relevant schema types, basic string, number and array length validations and string patterns.

Resolves recurring schemas with internal $refs.

Usage:

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()]),
});

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

Expected output:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$ref": "#/definitions/mySchema",
  "definitions": {
    "mySchema": {
      "type": "object",
      "properties": {
        "myString": {
          "type": "string",
          "minLength": 5
        },
        "myUnion": {
          "type": ["number", "boolean"]
        }
      },
      "additionalProperties": false,
      "required": ["myString", "myUnion"]
    }
  }
}

Changelog

Version	Change
3.4.0	Added support for z.lazy()
3.3.0	Added support for catchall (additionalProperties schema on objects). Rebuilt object parser.
3.2.0	Added support for Map and Set as seen by their most common JSON definitions. Beware no standardized definition seem to exist and JSON.parse doesn't handle either natively. Their implementations here are based on the spread approach. Also further simplified intersection definition to just allOf.
3.1.0	String patterns finally supported! Fixed bugs include broken external type, unsafe nullable parsing, bad intersection implementation, and missing support for passthrough keys in objects.
3.0.3	Fixed array deep pathing bug (path contained array instead of items)
3.0.2	Fixed broken type usage (NonEmptyArrayDefinition was removed from Zod)
3.0.1	Fixed a typo in the readme
3.0.0	Compatible with Zod 3.2.0. Huge props to Mr Hammad Asif for his work on this.
0.6.2	Hotfix for undefined object properties. Could crash the parser when using Pick
0.6.1	Fixed bug in union pathing. $Ref was missing /anyOf
0.6.0	Moved @types/json-schema and typescript to dev dependencies. @types/json-schema is now only used for the test suites. Using strict: true in ts config.
0.5.1	First working release with all relevant Zod types present with most validations (except for string patterns due to Zod not exposing the source regexp pattern for those).
< 0.5.1	Deprecated due to broken package structure. Please be patient, I eat crayons.