Overview: Zod v4.6.7 API Reference Catalog

This catalog provides a comprehensive, symbol-indexed API reference for Zod v4 (v4.6.7) across all public package entrypoints (zod, zod/mini, zod/v4/core, zod/locales, zod/compile, and zod/v3). Use the left sidebar or press / to filter classes, constructors, check functions, and types by name or semantic badge.

00_overview_1
Zod v4.6.7 Package Subpaths & 5-Module API Reference Catalog Topology
Source Code 
from drawlib import canvas
from drawlib.diagrams.architecture import ArchitectureDiagram, Node, NodeGroup, PhosphorIcon
from drawlib.styles import Styles
from drawlib.text import text

canvas.clear()
canvas.setup(width=180, height=102, dpi=150)

text(
    (90, 97.0),
    "Zod v4.6.7 Public Subpaths -> 5 Catalog Reference Modules",
    style=Styles.DarkBold.patch(text_size=13.0),
)

d = ArchitectureDiagram(
    node_style=Styles.PrimaryBold,
    node_text_style=Styles.DarkBold.patch(text_size=10.5),
    edge_style=Styles.PrimaryBold,
    edge_text_style=Styles.DarkBold.patch(text_size=10.0),
    node_card_style=Styles.Neutral,
)

# Left Group: Public Package Subpath Exports
pkg_group = d.add(
    NodeGroup(title="Package Entrypoints (package.json)", padding=5.0),
    xy=(2.0, 4.0),
)

sub_classic = pkg_group.add(
    Node(
        "zod (.) / zod/v4\nClassic Method API",
        width=48,
        height=14,
        icon=PhosphorIcon.PACKAGE,
        icon_size=6.0,
        style=Styles.WhiteBold,
        text_style=Styles.WhiteBold.patch(text_size=10.5),
        card_style=Styles.PrimaryFlat,
    ),
    xy=(29.0, 68.0),
)
sub_locales = pkg_group.add(
    Node(
        "zod/locales\n50 I18n Locale Packs",
        width=48,
        height=14,
        icon=PhosphorIcon.GLOBE,
        icon_size=6.0,
        card_style=Styles.Neutral,
    ),
    xy=(29.0, 49.0),
)
sub_mini = pkg_group.add(
    Node(
        "zod/mini\nTree-Shakeable API",
        width=48,
        height=14,
        icon=PhosphorIcon.FEATHER,
        icon_size=6.0,
        card_style=Styles.PrimaryNeutral,
    ),
    xy=(29.0, 30.0),
)
sub_core = pkg_group.add(
    Node(
        "zod/v4/core & compile\n$Zod* Engine + AOT AST",
        width=48,
        height=14,
        icon=PhosphorIcon.CPU,
        icon_size=6.0,
        card_style=Styles.PrimaryNeutral,
    ),
    xy=(29.0, 11.0),
)

# Right Group: 5 API Reference Catalog Pages
cat_group = d.add(
    NodeGroup(title="API Reference Catalog Modules (01 - 05)", padding=5.0),
    xy=(88.0, 4.0),
)

mod01 = cat_group.add(
    Node(
        "01. Primitives & Formats\nz.string / number / iso / uuid",
        width=68,
        height=12.5,
        icon=PhosphorIcon.TEXT_AA,
        icon_size=5.5,
        card_style=Styles.Neutral,
    ),
    xy=(39.0, 71.0),
)
mod02 = cat_group.add(
    Node(
        "02. Objects & Combinators\nZodObject / Array / Union / Optional",
        width=68,
        height=12.5,
        icon=PhosphorIcon.CUBE,
        icon_size=5.5,
        card_style=Styles.Neutral,
    ),
    xy=(39.0, 55.0),
)
mod03 = cat_group.add(
    Node(
        "03. Checks & Codecs\nz.check / refine / pipe / codec",
        width=68,
        height=12.5,
        icon=PhosphorIcon.ARROWS_LEFT_RIGHT,
        icon_size=5.5,
        card_style=Styles.PrimaryNeutral,
    ),
    xy=(39.0, 39.0),
)
mod04 = cat_group.add(
    Node(
        "04. Parsing, Errors & JSON Schema\nparse / ZodError / registry / toJSONSchema",
        width=68,
        height=12.5,
        icon=PhosphorIcon.FILE_CODE,
        icon_size=5.5,
        card_style=Styles.Neutral,
    ),
    xy=(39.0, 23.0),
)
mod05 = cat_group.add(
    Node(
        "05. Mini & Core Engine\nzod/mini / $constructor / compile",
        width=68,
        height=12.5,
        icon=PhosphorIcon.LIGHTNING,
        icon_size=5.5,
        style=Styles.WhiteBold,
        text_style=Styles.WhiteBold.patch(text_size=10.5),
        card_style=Styles.AccentFlat,
    ),
    xy=(39.0, 7.0),
)

# Planar orthogonal bus channels (at x=78, x=71, and x=65) with zero crossings
sub_classic.fork([mod01, mod02, mod03, mod04], at_x=78.0, padding=1.5)
d.connect(sub_locales, mod04, padding=1.5).via((71.0, 53.0), (71.0, 27.0))
d.connect(sub_mini, mod05, style=Styles.AccentBold, padding=1.5).via((65.0, 34.0), (65.0, 11.0))
d.connect(sub_core, mod05, style=Styles.AccentBold, padding=1.5).via((65.0, 15.0), (65.0, 11.0))

d.draw(xy=(4.0, 2.0))
canvas.save()

packagezod (Subpath Exports)#

Zod v4.6.7 exposes multiple subpath exports in packages/zod/package.json so applications and library authors can choose between ergonomic method chaining (zod), maximum tree-shaking (zod/mini), or direct access to the shared schema foundation (zod/v4/core).

00_overview_2
Package Subpath Exports Matrix (packages/zod/package.json)
Source Code 
from drawlib.canvas import save, setup
from drawlib.smartarts import Table
from drawlib.styles import Colors, Styles
from drawlib.text import text

setup(width=184, height=68, dpi=150)

text(
    (92, 63.5),
    "Zod v4.6.7 Package Subpath Exports & Target Modules",
    style=Styles.DarkBold.patch(text_size=12.5),
)

table = Table(
    cell_style=Styles.White,
    text_style=Styles.Dark.patch(text_size=10.0),
    header_cell_style=Styles.PrimaryFlat,
    header_text_style=Styles.WhiteBold.patch(text_size=10.5),
    border_style=Styles.MutedThin,
)

table.set_style_cell_evenodd(
    even_color=Colors.Light,
    even_text_style=Styles.Dark.patch(text_size=10.0),
    odd_color=Colors.White,
    odd_text_style=Styles.Dark.patch(text_size=10.0),
)
table.set_style_cell_header(
    background_color=Colors.Primary,
    text_style=Styles.WhiteBold.patch(text_size=10.5),
)
table.set_style_cell(
    background_color=Colors.Light,
    text_style=Styles.PrimaryBold.patch(text_size=10.0),
    rows=[1, 2, 3, 4, 5, 6],
    columns=[0],
)

data = [
    ["Import Subpath", "Source Entrypoint", "Primary Exported Symbols", "Bundle & Runtime Profile"],
    ["zod (.) / zod/v4", "src/v4/classic/external.ts", "z, ZodType, ZodObject, toJSONSchema", "Default en() locale on first init"],
    ["zod/mini", "src/v4/mini/external.ts", "z, ZodMiniType, check, minLength", "Side-effect free; tree-shakeable"],
    ["zod/v4/core", "src/v4/core/index.ts", "$constructor, $ZodType, $ZodRegistry", "Zero-locale shared core engine"],
    ["zod/locales", "src/v4/locales/index.ts", "en, ja, de, fr, es, zhCN (50 locales)", "Lazy per-locale error message maps"],
    ["zod/compile", "src/compile.ts", "compile, withParser, CompileOptions", "Installs global JIT / AOT hook"],
    ["zod/v3", "src/v3/index.ts", "Legacy Zod v3 compatibility exports", "Side-by-side v3 -> v4 migration"],
]

table.draw_flexible(
    xy=(4, 58),
    column_widths=[32, 42, 52, 50],
    row_heights=[8.0, 7.5, 7.5, 7.5, 7.5, 7.5, 7.5],
    data=data,
    align="top_left",
)

save()
Import Path Source File Key Exports Recommended Use Case
import { z } from "zod" packages/zod/src/index.ts ZodType, z.string(), z.object(), .parse(), .toJSONSchema() Standard application development with full fluent method chaining and default English locale.
import * as z from "zod/mini" packages/zod/src/mini/index.ts ZodMiniType, z.string(), z.check(), z.minLength(), z.parse() Frontend bundles and edge workers requiring strict dead-code elimination (sideEffects: false).
import * as core from "zod/v4/core" packages/zod/src/v4/core/index.ts $constructor, $ZodType, $ZodCheck, $ZodError, $ZodRegistry Building custom schema libraries, framework adapters, or tools that accept both Classic and Mini schemas.
import { ja } from "zod/locales" packages/zod/src/locales/index.ts 50 locale factories (en(), ja(), de(), fr(), es(), ...) Internationalized validation error messages configured via z.config(ja()).
import "zod/compile" packages/zod/src/compile.ts compile(schema), withParser(schema, fn) Ahead-of-time (AOT) and JIT JavaScript code generation for high-throughput validation paths.
import * as z3 from "zod/v3" packages/zod/src/v3/index.ts Legacy Zod v3 classes and methods Gradual migration of large monorepos from Zod v3 to Zod v4.

moduleCatalog Module Index#

The API Reference Catalog is organized into five domain modules:

Module Page Scope & Covered Symbols Key Classes & Functions
01. Primitives, Coercion & String Formats Scalar primitives, numeric/bigint bit-width formats, z.coerce, top-level string format schemas, and z.iso.* temporal types z.string, z.number, z.int, z.bigint, z.boolean, z.stringbool, z.date, z.literal, z.enum, z.templateLiteral, z.coerce, z.email, z.uuid, z.url, z.jwt, z.ipv4, z.ipv6, z.iso
02. Objects, Collections, Unions & Combinators Object schemas, collection containers, set-theoretic unions/intersections, and wrapper modifiers ZodObject, z.object, z.strictObject, z.looseObject, ZodArray, ZodTuple, ZodRecord, ZodMap, ZodSet, ZodUnion, ZodXor, ZodDiscriminatedUnion, ZodIntersection, ZodOptional, ZodNullable, ZodDefault, ZodPrefault, ZodCatch, ZodReadonly, z.lazy, z.custom, ZodFunction, ZodPromise
03. Checks, Refinements, Transforms & Codecs Composable $ZodCheck validators, custom refinements, unidirectional pipelines, and bidirectional ZodCodec z.check, schema.check, schema.refine, schema.superRefine, schema.overwrite, z.transform, z.pipe, z.codec, z.invertCodec, z.preprocess, z.stringbool, string/number/size check helpers
04. Parsing, Errors, Registries & JSON Schema Forward/backward execution (parse/decode/encode), error formatting utilities, metadata registries, and JSON Schema round-tripping z.parse, z.safeParse, z.encode, z.decode, ZodError, $ZodIssue, z.treeifyError, z.prettifyError, z.flattenError, z.registry, z.globalRegistry, schema.meta, z.toJSONSchema, z.fromJSONSchema, z.config, z.locales
05. zod/mini, zod/v4/core & AOT Compiler Functional ZodMiniType wrappers, $constructor prototype engine, Standard Schema v1 integration, and code compilation ZodMiniType, core.$constructor, core.$ZodType, core.$ZodCheck, ~standard, z.compile, z.withParser, ZodCompileAsyncError, ZodCompileUnsupportedError, z.infer, z.input, z.output

interfaceZodType<Output, Input, Internals>#

Every schema in the classic zod entrypoint inherits from ZodType<Output, Input, Internals>, which extends core.$ZodType and attaches ergonomic instance methods on the prototype.

export interface ZodType<
  out Output = unknown,
  out Input = unknown,
  out Internals extends core.$ZodTypeInternals<Output, Input> = core.$ZodTypeInternals<Output, Input>,
> extends core.$ZodType<Output, Input, Internals>
Property / Method Group Signature Description
.def / .type Internals["def"] / Internals["def"]["type"] Inspects the immutable schema definition object and discriminant string (e.g. "string", "object", "union").
["~standard"] ZodStandardSchemaWithJSON<this> Implements the Standard Schema v1 specification (validate, vendor: "zod", and jsonSchema.input/output).
.parse(data, params?) (data: unknown, params?: ParseContext) => Output Synchronously validates data in the forward direction and returns typed Output or throws ZodError.
.safeParse(data, params?) (data: unknown, params?: ParseContext) => ZodSafeParseResult<Output> Returns { success: true, data: Output } | { success: false, error: ZodError } without throwing.
.parseAsync(data, params?) (data: unknown, params?: ParseContext) => Promise<Output> Asynchronously validates schemas containing async refinements or transforms.
.safeParseAsync(data, params?) / .spa (data: unknown, params?: ParseContext) => Promise<ZodSafeParseResult<Output>> Non-throwing asynchronous parse (schema.spa is a direct alias).
.encode(data, params?) / .decode(data, params?) encode(Output): Input / decode(Input): Output Bidirectional codec execution; .encode() runs pipes and codecs in reverse (direction: "backward").
.check(...checks) / .with(...checks) (...checks: ($ZodCheck<Output> | CheckFn<Output>)[]) => this Clones the schema and appends one or more composable validation or mutation checks.
.refine(fn, params?) / .superRefine(fn, params?) Custom predicate or multi-issue validation Appends custom synchronous or asynchronous validation logic to the schema's check pipeline.
.optional() / .nullable() / .nullish() Wrapper combinators Wraps this in ZodOptional, ZodNullable, or ZodOptional<ZodNullable<this>>.
.default(val) / .prefault(val) / .catch(val) Fallback value wrappers Short-circuits undefined (default), feeds default into input (prefault), or recovers from parse errors (catch).
.pipe(target) / .transform(fn) ZodPipe<this, T> Chains output of this into target or into a ZodTransform stage.
.describe(text) / .meta(data?) / .register(reg, meta?) Metadata & Registry attachment Associates documentation and JSON Schema metadata in z.globalRegistry or a custom $ZodRegistry.
.toJSONSchema(params?) (params?: ToJSONSchemaParams) => JSONSchema Converts this schema directly to Draft-2020-12, Draft-07, Draft-04, or OpenAPI 3.0 JSON Schema.
.brand<T, Dir?>() <T extends PropertyKey, Dir = "out">() => $ZodBranded<this, T, Dir> Attaches a compile-time nominal brand symbol ($brand) to output, input, or both.

typeSchemaParams & Error Customization#

All schema constructors and check functions in Zod v4 accept a unified params argument (string | { error?: string | $ZodErrorMap, ... }), replacing the fragmented invalid_type_error / required_error options from Zod v3.

Parameter Field Type Applicable Scope Behavior
params (shorthand) string All constructors & checks Normalized automatically to { error: params } via util.normalizeParams().
error string | $ZodErrorMap<Issue> All constructors & checks Custom static error string or per-issue callback (iss) => string | { message: string } | undefined.Returning undefined falls back to the active locale.
abort boolean .refine(), .superRefine(), checks When true, halts subsequent checks on this schema if this check emits an issue.
path PropertyKey[] .refine(), z.custom(), checks Appends a relative property path to issues emitted by the check.
when (payload: ParsePayload) => boolean .refine(), $ZodCheck Conditional guard determining whether the check should execute for a given payload. 
import { z } from "zod";

// 1. Shorthand string error message
const NameSchema = z.string("Name must be a string").min(2, "At least 2 characters");

// 2. Dynamic error map function inspecting `iss.input`
const AgeSchema = z.int({
  error: (iss) =>
    iss.input === undefined ? "Age is required" : `Expected integer age, got ${typeof iss.input}`,
});