Zod to Json Schema

Looking for the exact opposite? Check out json-schema-to-zod

Summary

Does what it says on the tin; converts Zod schemas into JSON schemas!

• Supports all relevant schema types, basic string, number and array length validations and string patterns.
• Resolves recursive and recurring schemas with internal $refs.
• Supports targeting legacy Open API 3.0 specification (3.1 supports regular Json Schema).
• Supports Open AI strict mode schemas (Optional object properties are replaced with required but nullable ones).

Sponsors

If you enjoy this package, consider dropping a couple of bucks on my GitHub Sponsors page <3

Usage

Basic example

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

Expected output

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

Options

Schema name

You can pass a string as the second parameter of the main zodToJsonSchema function. If you do, your schema will end up inside a definitions object property on the root and referenced from there. Alternatively, you can pass the name as the name property of the options object (see below).

Options object

Instead of the schema name (or nothing), you can pass an options object as the second parameter. The following options are available:

Definitions

The definitions option lets you manually add recurring schemas into definitions for cleaner outputs. It's fully compatible with named schemas, changed definitions path and base path. Here's a simple example:

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

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

Result

{
  "type": "object",
  "properties": {
    "a": {
      "$ref": "#/definitions/myRecurringSchema"
    },
    "b": {
      "$ref": "#/definitions/myRecurringSchema"
    }
  },
  "definitions": {
    "myRecurringSchema": {
      "type": "string"
    }
  }
}

Error Messages

This feature allows optionally including error messages created via chained function calls for supported zod types:

// string schema with additional chained function call checks
const EmailSchema = z.string().email("Invalid email").min(5, "Too short");

const jsonSchema = zodToJsonSchema(EmailSchema, { errorMessages: true });

Result

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "string",
  "format": "email",
  "minLength": 5,
  "errorMessage": {
    "format": "Invalid email",
    "minLength": "Too short"
  }
}

This allows for field specific, validation step specific error messages which can be useful for building forms and such. This format is accepted by react-hook-form's ajv resolver (and therefor ajv-errors which it uses under the hood). Note that if using AJV with this format will require enabling ajv-errors as vanilla AJV does not accept this format by default.

Custom Error Message Support

• ZodString
  • regex
  • min, max
  • email, cuid, uuid, url
  • endsWith, startsWith
• ZodNumber
  • min, max, lt, lte, gt, gte,
  • int
  • multipleOf
• ZodSet
  • min, max
• ZodArray
  • min, max

override option

This options takes a Zod schema definition, the current reference object (containing the current ref path and other options), an argument containing inforation about wether or not the schema has been encountered before, and a forceResolution argument.

Since undefined is a valid option to return, if you don't want to override the current item you have to return the ignoreOverride symbol exported from the index.

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

zodToJsonSchema(
  z.object({
    ignoreThis: z.string(),
    overrideThis: z.string(),
    removeThis: z.string(),
  }),
  {
    override: (def, refs) => {
      const path = refs.currentPath.join("/");

      if (path === "#/properties/overrideThis") {
        return {
          type: "integer",
        };
      }

      if (path === "#/properties/removeThis") {
        return undefined;
      }

      // Important! Do not return `undefined` or void unless you want to remove the property from the resulting schema completely.
      return ignoreOverride;
    },
  },
);

Expected output:

{
  "type": "object",
  "required": ["ignoreThis", "overrideThis"],
  "properties": {
    "ignoreThis": {
      "type": "string"
    },
    "overrideThis": {
      "type": "integer"
    }
  },
  "additionalProperties": false
}

Known issues

• The OpenAI target should be considered experimental for now, as some combination of options may break the compatibility.
• When using .transform, the return type is inferred from the supplied function. In other words, there is no schema for the return type, and there is no way to convert it in runtime. Currently the JSON schema will therefore reflect the input side of the Zod schema and not necessarily the output (the latter aka. z.infer). If this causes problems with your schema, consider using the effectStrategy "any", which will allow any type of output.
• JSON Schemas does not support any other key type than strings for objects. When using z.record with any other key type, this will be ignored. An exception to this rule is z.enum as is supported since 3.11.3
• Relative JSON pointers, while published alongside JSON schema draft 2020-12, is not technically a part of it. Currently, most resolvers do not handle them at all.
• Since v3, the Object parser uses .isOptional() to check if a property should be included in required or not. This has the potentially dangerous behavior of calling .safeParse with undefined. To work around this, make sure your preprocess and other effects callbacks are pure and not liable to throw errors. An issue has been logged in the Zod repo and can be tracked here.

Versioning

This package does not follow semantic versioning. The major and minor versions of this package instead reflects feature parity with the Zod package.

I will do my best to keep API-breaking changes to an absolute minimum, but new features may appear as "patches", such as introducing the options pattern in 3.9.1.

Changelog

https://github.com/StefanTerdell/zod-to-json-schema/blob/master/changelog.md

Changelog