or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

advanced-features.mdconfiguration.mdindex.mdschema-conversion.mdtypes.md
tile.json

tessl/npm-zod-to-json-schema

Converts Zod schemas to JSON Schema format with support for multiple targets and extensive configuration options

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/zod-to-json-schema@3.24.x

To install, run

npx @tessl/cli install tessl/npm-zod-to-json-schema@3.24.0

index.mddocs/

Zod to JSON Schema

Zod to JSON Schema converts Zod schemas into JSON Schema format, enabling seamless integration between Zod's runtime validation system and JSON Schema-based tools and APIs. It supports all Zod schema types including complex ones like unions, intersections, and recursive schemas, with advanced features like reference resolution, multiple target formats, and extensive configuration options.

Package Information

  • Package Name: zod-to-json-schema
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install zod-to-json-schema

Core Imports

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

For default import:

import zodToJsonSchema from "zod-to-json-schema";

For CommonJS:

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

Basic 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()]),
  })
  .describe("My neat object schema");

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

Architecture

Zod to JSON Schema is built around several key components:

  • Core Conversion: zodToJsonSchema function that orchestrates the conversion process
  • Parser System: Specialized parsers for each Zod schema type (string, object, array, etc.)
  • Configuration System: Extensive options for customizing output format and behavior
  • Reference Resolution: Advanced system for handling circular references and reused schemas
  • Target Support: Multiple output formats including JSON Schema 7, JSON Schema 2019-09, OpenAPI 3.0, and OpenAI

Capabilities

Schema Conversion

Core functionality for converting Zod schemas to JSON Schema format with comprehensive type support and flexible configuration.

function zodToJsonSchema<Target extends Targets = "jsonSchema7">(
  schema: ZodSchema<any>,
  options?: Partial<Options<Target>> | string
): (Target extends "jsonSchema7" ? JsonSchema7Type : object) & {
  $schema?: string;
  definitions?: {
    [key: string]: Target extends "jsonSchema7"
      ? JsonSchema7Type
      : Target extends "jsonSchema2019-09"
        ? JsonSchema7Type
        : object;
  };
};

Schema Conversion

Configuration Options

Comprehensive configuration system for customizing conversion behavior, target formats, and output structure.

interface Options<Target extends Targets = "jsonSchema7"> {
  name: string | undefined;
  $refStrategy: "root" | "relative" | "none" | "seen";
  basePath: string[];
  effectStrategy: "input" | "any";
  pipeStrategy: "input" | "output" | "all";
  dateStrategy: DateStrategy | DateStrategy[];
  mapStrategy: "entries" | "record";
  removeAdditionalStrategy: "passthrough" | "strict";
  target: Target;
  strictUnions: boolean;
  definitionPath: string;
  definitions: Record<string, ZodSchema>;
  errorMessages: boolean;
  markdownDescription: boolean;
  patternStrategy: "escape" | "preserve";
  applyRegexFlags: boolean;
  emailStrategy: "format:email" | "format:idn-email" | "pattern:zod";
  base64Strategy: "format:binary" | "contentEncoding:base64" | "pattern:zod";
  nameStrategy: "ref" | "title";
  override?: OverrideCallback;
  postProcess?: PostProcessCallback;
  openAiAnyTypeName: string;
}

type Targets = "jsonSchema7" | "jsonSchema2019-09" | "openApi3" | "openAi";
type DateStrategy = "format:date-time" | "format:date" | "string" | "integer";

Configuration Options

Type System

Complete type definitions for JSON Schema output and configuration, enabling full TypeScript integration.

type JsonSchema7Type = JsonSchema7TypeUnion & JsonSchema7Meta;

type JsonSchema7TypeUnion =
  | JsonSchema7StringType
  | JsonSchema7ArrayType
  | JsonSchema7NumberType
  | JsonSchema7BigintType
  | JsonSchema7BooleanType
  | JsonSchema7DateType
  | JsonSchema7EnumType
  | JsonSchema7LiteralType
  | JsonSchema7NativeEnumType
  | JsonSchema7NullType
  | JsonSchema7ObjectType
  | JsonSchema7RecordType
  | JsonSchema7TupleType
  | JsonSchema7UnionType
  | JsonSchema7UndefinedType
  | JsonSchema7RefType
  | JsonSchema7NeverType
  | JsonSchema7MapType
  | JsonSchema7AnyType
  | JsonSchema7NullableType
  | JsonSchema7AllOfType
  | JsonSchema7UnknownType
  | JsonSchema7SetType;

Type System

Advanced Features

Reference resolution, custom parsing, and post-processing capabilities for handling complex schemas and specialized requirements.

type OverrideCallback = (
  def: ZodTypeDef,
  refs: Refs,
  seen: Seen | undefined,
  forceResolution?: boolean
) => JsonSchema7Type | undefined | typeof ignoreOverride;

type PostProcessCallback = (
  jsonSchema: JsonSchema7Type | undefined,
  def: ZodTypeDef,
  refs: Refs
) => JsonSchema7Type | undefined;

interface Refs {
  seen: Map<ZodTypeDef, Seen>;
  currentPath: string[];
  propertyPath: string[] | undefined;
  flags: { hasReferencedOpenAiAnyType: boolean };
}

Advanced Features