Zod v4.6.7 User Guide — Overview & Quickstart

Welcome to the comprehensive Zod v4.6.7 User Guide. Zod is a TypeScript-first schema declaration, validation, and bidirectional transformation library with static type inference. Version 4.6.7 introduces a ground-up architectural redesign centered on a shared zod/v4/core engine, dual user-facing facades (zod and zod/mini), built-in JSON Schema synthesis, bidirectional codecs, JIT object compilation, and 49 localized error dictionaries.

from drawlib.canvas import save, setup
from drawlib.icons import phosphor
from drawlib.smartarts import CardList, KpiCards, Panel
from drawlib.styles import Styles

setup(width=168, height=74)

left_panel = Panel(
    "Zod v4.6.7 Core & Dual-Facade Architecture",
    "Unified Engine",
    style=Styles.Neutral,
    header_style=Styles.PrimaryNeutral.patch(shape_line_width=1.2),
    text_style=Styles.DarkBold.patch(text_size=11.5),
    description_style=Styles.Muted.patch(text_size=10.0),
    icon=phosphor.stack,
    icon_style=Styles.PrimaryBold,
    header_variant="filled",
    header_height=9.0,
)
left_panel.draw((5.0, 5.0), width=98.0, height=64.0, align="bottom_left")
c_xy, c_w, c_h = left_panel.get_content_box((5.0, 5.0), width=98.0, height=64.0, padding=(3.5, 3.0))

facade_list = CardList(
    style=Styles.White,
    text_style=Styles.DarkBold.patch(text_size=10.5),
    description_style=Styles.Muted.patch(text_size=10.0),
    badge_shape="rounded_rect",
    badge_style=Styles.PrimaryNeutral,
    badge_text_style=Styles.DarkBold.patch(text_size=10.0),
    spacing=2.2,
)
facade_list.add(
    "Classic Facade (zod)",
    "Ergonomic method chaining (.min(), .refine(), .transform())",
    badge_text="FULL",
    style=Styles.PrimaryFlat,
    text_style=Styles.WhiteBold.patch(text_size=10.5),
    description_style=Styles.White.patch(text_size=10.0),
    badge_style=Styles.White,
    badge_text_style=Styles.PrimaryBold.patch(text_size=10.0),
)
facade_list.add(
    "Tree-Shakeable Facade (zod/mini)",
    "Functional check composition (z.check(), ~85% smaller bundles)",
    badge_text="MINI",
)
facade_list.add(
    "Shared Core Engine (zod/v4/core)",
    "$constructor traits, JIT compiler, Codecs & Standard Schema",
    badge_text="CORE",
)
facade_list.draw(c_xy, width=c_w, height=c_h)

kpi = KpiCards(
    style=Styles.Neutral,
    metric_style=Styles.PrimaryBold.patch(text_size=12.5),
    text_style=Styles.DarkBold.patch(text_size=10.5),
    description_style=Styles.Muted.patch(text_size=10.0),
    accent_style=Styles.PrimaryFlat,
    accent_position="left_pill",
    metric_layout="left_column",
    metric_width_ratio=0.35,
    spacing=2.5,
)
kpi.add("z.infer<T>", "Static Inference", "Input & Output TS types")
kpi.add("Draft-2020", "JSON Schema", "Native to/fromJSONSchema")
kpi.add("49 Locales", "Built-in i18n", "Localized issue diagnostics")
kpi.add(
    "JIT Speed",
    "Object Compiler",
    "Fast-path property checks",
    metric_style=Styles.AccentBold.patch(text_size=12.5),
    accent_style=Styles.AccentFlat,
)
kpi.draw((107.0, 5.0), width=56.0, height=64.0, columns=1, align="bottom_left")

save()

Why Zod v4.6.7?

TypeScript's type system is erased entirely at build time. Network payloads, JSON.parse() outputs, environment variables, form submissions, and LLM tool calls enter your runtime as untrusted unknown values. Zod v4.6.7 bridges the boundary between compile-time TypeScript types and runtime data invariants from a single declarative definition:

1. Dual Facades over a Unified Core (zod & zod/mini): Choose ergonomic method-chaining via import { z } from "zod" or ultra-compact tree-shakeable functional composition via import * as z from "zod/mini", both backed by identical zod/v4/core schema internals ($ZodType).
2. First-Class String Formats & Numeric Types: Formats such as z.email(), z.uuid(), z.url(), z.jwt(), z.ipv4(), z.cidrv4(), and z.iso.datetime() are promoted to top-level schema constructors alongside fixed-width numbers (z.int(), z.int32(), z.uint32(), z.float32(), z.float64(), z.int64()).
3. Bidirectional Codecs (z.codec()): Unlike one-way .transform() pipelines, z.codec(inputSchema, outputSchema, { decode, encode }) enables type-safe forward decoding (z.decode()) and reverse serialization (z.encode()).
4. Metadata Registries & Native JSON Schema: Attach strongly typed metadata via z.registry<Meta>() or .meta() and convert schemas bidirectionally with z.toJSONSchema() and z.fromJSONSchema().
5. Structured Error Formatting & 49 Locales: Format validation failures into nested trees (z.treeifyError()), human-readable CLI summaries (z.prettifyError()), or flat form maps (z.flattenError()) across 49 built-in locales (z.locales.ja(), z.locales.en(), etc.).

Validation Lifecycle at a Glance

Every schema validation call in Zod v4 flows through a deterministic pipeline managed by zod/v4/core:

from drawlib.canvas import save, setup
from drawlib.diagrams.flow import Decision, End, FlowDiagram, Process, Start
from drawlib.styles import Colors, Styles

setup(width=166, height=70)

flow = FlowDiagram(
    node_style=Styles.Neutral.patch(text_size=10.5),
    edge_style=Styles.DarkBold,
    edge_text_style=Styles.DarkBold.patch(text_size=10.0),
    title="Zod v4 Runtime Validation & SafeParse Pipeline",
    title_style=Styles.DarkBold.patch(text_size=13.0),
)

inp = flow.add(
    Start(
        "Untrusted Input\n(unknown)",
        width=25,
        height=13,
        style=Styles.PrimaryFlat.patch(text_color=Colors.White, text_size=10.5),
    ),
    xy=(15, 31),
)
entry = flow.add(
    Process("schema.safeParse()\nInit ParsePayload", width=29, height=14, style=Styles.PrimaryNeutral.patch(text_size=10.5)),
    xy=(49, 31),
)
checks = flow.add(
    Process("Base Type & Checks\n($ZodCheck Pipeline)", width=30, height=14, style=Styles.Neutral.patch(text_size=10.5)),
    xy=(86, 31),
)
dec = flow.add(
    Decision("issues.length\n=== 0 ?", width=24, height=16, style=Styles.SecondaryNeutral.patch(text_size=10.5)),
    xy=(120, 31),
)
ok = flow.add(
    End("Success Result\n{ success: true, data: T }", width=30, height=13, style=Styles.SuccessNeutral.patch(text_size=10.5)),
    xy=(146, 50),
)
err = flow.add(
    End("Failure Result\n{ success: false, error }", width=30, height=13, style=Styles.DangerNeutral.patch(text_size=10.5)),
    xy=(146, 12),
)

inp.connect(entry, padding=1.0)
entry.connect(checks, padding=1.0)
checks.connect(dec, padding=1.0)
dec.connect(ok, label="Yes", start_side="top", end_side="left", padding=1.0)
dec.connect(err, label="No", start_side="bottom", end_side="left", padding=1.0)

flow.draw(xy=(3.0, 3.0))
save()

60-Second Quickstart

Define a schema once, infer its static TypeScript type with z.infer<typeof Schema>, validate untrusted payloads at runtime with .safeParse(), and export standard JSON Schema definitions:

import { z } from "zod";

// 1. Define a schema with top-level v4 formats and metadata
const UserSchema = z
  .object({
    id: z.uuid(),
    email: z.email(),
    username: z.string().min(3).max(24).trim(),
    role: z.enum(["admin", "editor", "viewer"]).default("viewer"),
    age: z.int().min(18).optional(),
    createdAt: z.iso.datetime(),
  })
  .meta({
    id: "User",
    title: "Application User Account",
  });

// 2. Extract the static TypeScript Output & Input types
type User = z.infer<typeof UserSchema>;
type UserInput = z.input<typeof UserSchema>; // `role` is optional in input

// 3. Validate untrusted data without throwing exceptions
const result = UserSchema.safeParse({
  id: "550e8400-e29b-41d4-a716-446655440000",
  email: "alice@example.com",
  username: "  alice_dev  ",
  createdAt: "2026-11-10T10:00:00Z",
});

if (!result.success) {
  console.error(z.prettifyError(result.error));
} else {
  // result.data is narrowed to `User` (username trimmed, role defaulted to "viewer")
  console.log(result.data.username, result.data.role);
}

// 4. Generate Draft-2020-12 JSON Schema directly
const jsonSchema = z.toJSONSchema(UserSchema);

Choosing the Right Subpath (zod vs zod/mini vs zod/v4/core)

Zod v4.6.7 ships multiple subpath exports in package.json tailored for backend servers, size-constrained edge/browser bundles, and third-party library authors:

Guide Structure & Chapter Roadmap

This portal is organized into three progressive sections covering everyday validation through advanced compiler optimizations:

Part I — Getting Started

• 1. Installation, Strict Mode & Type Inference: Installing zod@4.6.7, why "strict": true in tsconfig.json is mandatory, choosing between parse / safeParse / parseAsync / encode / decode, and extracting z.infer<T>, z.input<T>, and z.output<T>.
• 2. Primitives, Literals & String Formats: Complete taxonomy of Zod v4 primitives (string, int, float32, float64, bigint, boolean, date, literal, enum), top-level string format validators (z.email(), z.uuid(), z.url(), z.jwt(), z.ipv4(), z.iso.*), z.templateLiteral(), z.coerce.*, and z.stringbool().

Part II — Structured Schemas & Composition

• 3. Objects, Records, Tuples & Recursion: z.object(), z.strictObject(), z.looseObject(), .extend(), .pick(), .omit(), .partial(), z.record(), z.tuple(), z.map(), z.set(), and native getter-based recursive schemas.
• 4. Unions, Discriminated Unions & Intersections: z.union(), constant-time $O(1)$ dispatch with z.discriminatedUnion(), z.xor(), and z.intersection().
• 5. Refinements, Pipelines & Bidirectional Codecs: Custom checks with .refine(), .superRefine(), .check(), .overwrite(), unidirectional .pipe() / .transform(), and reversible z.codec() pipelines.

Part III — Errors, Interop & Optimization

• 6. Error Formatting & 49 i18n Locales: Inspecting $ZodIssue trees, formatting errors with z.treeifyError(), z.prettifyError(), and z.flattenError(), custom error maps, and configuring 49 built-in locales.
• 7. Metadata Registries & JSON Schema: Strongly typed metadata registries (z.registry<Meta>()), z.globalRegistry, OpenAPI/AI tool generation via z.toJSONSchema(), and runtime hydration via z.fromJSONSchema().
• 8. Tree-Shaking with zod/mini & JIT Compilation: Migrating hot paths to zod/mini, functional z.check() combinators, $ZodObjectJIT fast-path execution, and ahead-of-time z.compile().

Companion Documentation Portals

Explore the companion portals in the Zod v4.6.7 documentation suite for deep API signatures, internal engine mechanics, and architectural diagnostics:

• API Reference Catalog: Exhaustive signature-level reference for every schema constructor, check function, codec helper, error formatter, and JSON Schema processor.
• Internal Architecture Guide: Deep dive into zod/v4/core, $constructor prototype synthesis, ParsePayload state machines, and JIT code generation.
• PNI501 Diagnostic Report: Engineering analysis of Zod v4.6.7 performance characteristics, bundle size benchmarks, and edge-case behaviors.