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

Type System

Name: tessl/npm-zod-to-json-schema
Author: tessl

The zod-to-json-schema library provides comprehensive TypeScript type definitions for JSON Schema output, configuration options, and internal structures. This ensures full type safety when working with the library.

Core JSON Schema Types

`JsonSchema7Type`

type JsonSchema7Type = JsonSchema7TypeUnion & JsonSchema7Meta;

type JsonSchema7Meta = {
  title?: string;
  default?: any;
  description?: string;
  markdownDescription?: string;
};

The main type representing a complete JSON Schema with metadata.

`JsonSchema7TypeUnion`

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;

Union of all specific JSON Schema types without metadata.

Specific Schema Types

String Types

type JsonSchema7StringType = {
  type: "string";
  minLength?: number;
  maxLength?: number;
  format?:
    | "email"
    | "idn-email"
    | "uri"
    | "uuid"
    | "date-time"
    | "ipv4"
    | "ipv6"
    | "date"
    | "time"
    | "duration";
  pattern?: string;
  allOf?: {
    pattern: string;
    errorMessage?: ErrorMessages<{ pattern: string }>;
  }[];
  anyOf?: {
    format: string;
    errorMessage?: ErrorMessages<{ format: string }>;
  }[];
  errorMessage?: ErrorMessages<JsonSchema7StringType>;
  contentEncoding?: string;
};

Number Types

type JsonSchema7NumberType = {
  type: "number" | "integer";
  minimum?: number;
  maximum?: number;
  exclusiveMinimum?: number;
  exclusiveMaximum?: number;
  multipleOf?: number;
};

type JsonSchema7BigintType = {
  type: "integer";
  minimum?: number;
  maximum?: number;
  exclusiveMinimum?: number;
  exclusiveMaximum?: number;
  multipleOf?: number;
};

Boolean Type

type JsonSchema7BooleanType = {
  type: "boolean";
};

Array Types

type JsonSchema7ArrayType = {
  type: "array";
  items?: JsonSchema7Type;
  minItems?: number;
  maxItems?: number;
  uniqueItems?: boolean;
};

type JsonSchema7TupleType = {
  type: "array";
  items: JsonSchema7Type[];
  minItems?: number;
  maxItems?: number;
  additionalItems?: boolean | JsonSchema7Type;
};

type JsonSchema7SetType = {
  type: "array";
  items?: JsonSchema7Type;
  uniqueItems: true;
  minItems?: number;
  maxItems?: number;
};

Object Types

type JsonSchema7ObjectType = {
  type: "object";
  properties: Record<string, JsonSchema7Type>;
  additionalProperties?: boolean | JsonSchema7Type;
  required?: string[];
  minProperties?: number;
  maxProperties?: number;
};

type JsonSchema7RecordType = {
  type: "object";
  additionalProperties: JsonSchema7Type;
  minProperties?: number;
  maxProperties?: number;
};

Union and Intersection Types

type JsonSchema7UnionType = {
  anyOf: JsonSchema7Type[];
} | {
  type: (string | number | boolean | null)[];
} | {
  oneOf: JsonSchema7Type[];
};

type JsonSchema7AllOfType = {
  allOf: JsonSchema7Type[];
};

Literal and Enum Types

type JsonSchema7LiteralType = {
  const: any;
} | {
  type: "string" | "number" | "boolean" | "null";
  enum: [any];
};

type JsonSchema7EnumType = {
  type: "string";
  enum: string[];
};

type JsonSchema7NativeEnumType = {
  type: "string" | "number";
  enum: (string | number)[];
};

Special Types

type JsonSchema7RefType = {
  $ref: string;
};

type JsonSchema7NullType = {
  type: "null";
};

type JsonSchema7UndefinedType = {
  not: {};
} | {
  type: never[];
};

type JsonSchema7NeverType = {
  not: {};
} | {
  type: never[];
};

type JsonSchema7AnyType = {};

type JsonSchema7UnknownType = {};

type JsonSchema7NullableType = {
  anyOf: [JsonSchema7Type, { type: "null" }];
} | {
  type: (string | number | boolean | null)[];
};

type JsonSchema7DateType = {
  type: "string";
  format: "date-time" | "date";
} | {
  type: "string";
} | {
  type: "integer";
  minimum?: number;
};

type JsonSchema7MapType = {
  type: "array";
  items: {
    type: "array";
    items: [JsonSchema7Type, JsonSchema7Type];
    minItems: 2;
    maxItems: 2;
  };
} | JsonSchema7RecordType;

Configuration Types

`Targets`

type Targets = "jsonSchema7" | "jsonSchema2019-09" | "openApi3" | "openAi";

`DateStrategy`

type DateStrategy = "format:date-time" | "format:date" | "string" | "integer";

Callback Types

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;

Reference System Types

`Refs`

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

`Seen`

interface Seen {
  def: ZodTypeDef;
  path: string[];
  jsonSchema: JsonSchema7Type | undefined;
}

Error Handling Types

`ErrorMessages`

type ErrorMessages<
  T extends JsonSchema7TypeUnion | { format: string } | { pattern: string },
  OmitProperties extends string = ""
> = Partial<
  Omit<{ [key in keyof T]: string }, OmitProperties | "type" | "errorMessages">
>;

Utility Types

`InnerDefGetter`

type InnerDefGetter = () => any;

Used for lazy evaluation in recursive schema parsing.

Constants and Symbols

`ignoreOverride`

const ignoreOverride: unique symbol;

Symbol used in override callbacks to indicate the default parser should be used.

Built-in Post-processor

const jsonDescription: PostProcessCallback;

Built-in post-processor that parses JSON from Zod schema descriptions.

Type Guards and Utilities

Pattern Definitions

const zodPatterns: {
  cuid: RegExp;
  cuid2: RegExp;
  ulid: RegExp;
  email: RegExp;
  emoji: () => RegExp;
  uuid: RegExp;
  ipv4: RegExp;
  ipv4Cidr: RegExp;
  ipv6: RegExp;
  ipv6Cidr: RegExp;
  base64: RegExp;
  base64url: RegExp;
  nanoid: RegExp;
  jwt: RegExp;
};

Pre-defined regex patterns for common string validations.

Usage with TypeScript

The type system enables full TypeScript integration:

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

// Type-safe options
const options: Options<"jsonSchema7"> = {
  name: "UserSchema",
  target: "jsonSchema7",
  dateStrategy: "format:date-time"
};

// Type-safe result
const result: JsonSchema7Type & { $schema?: string } = zodToJsonSchema(schema, options);

// Custom override with proper typing
const customOverride: OverrideCallback = (def, refs, seen, forceResolution) => {
  if (def.typeName === "ZodString") {
    return { type: "string", format: "custom" };
  }
  return ignoreOverride;
};

Install with Tessl CLI

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

docs