CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-zod-to-json-schema

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

Overview
Eval results
Files

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

Install with Tessl CLI

npx tessl i tessl/npm-zod-to-json-schema

docs

advanced-features.md

configuration.md

index.md

schema-conversion.md

types.md

tile.json