4. Parsing, Error Formatting, Registries, JSON Schema & Static Types

Beyond schema construction, Zod v4 provides standalone and method-based execution engines (parse, safeParse, validate, encode, decode), a streamlined 11-member $ZodIssue discriminated union with built-in formatters (prettifyError, treeifyError, flattenError, formatError), strongly-typed WeakMap metadata registries ($ZodRegistry, globalRegistry), bidirectional JSON Schema conversion (toJSONSchema, fromJSONSchema), and static/runtime input-output projection utilities (z.infer, z.input, z.output).

from drawlib import canvas
from drawlib.diagrams.architecture import ArchitectureDiagram, Node, NodeGroup, PhosphorIcon
from drawlib.styles import Styles

canvas.clear()
canvas.setup(width=188, height=96, dpi=150)

d = ArchitectureDiagram(
    node_style=Styles.Primary,
    node_text_style=Styles.DarkBold.patch(text_size=10.0),
    edge_style=Styles.DarkBold,
    edge_text_style=Styles.Dark.patch(text_size=10.0),
    node_card_style=Styles.Neutral,
    title="Zod v4 Execution, Error Formatting, Registry & JSON Schema Surface",
)

# Left Group: Parse & Codec Execution (node width=46 -> center x = 5 + 23 = 28)
exec_grp = d.add(
    NodeGroup(title="1. Parse & Codec Execution", padding=5.0),
    xy=(0.0, 0.0),
)
parse_node = exec_grp.add(
    Node("Forward Parse & Guard\nparse / safeParse\nparseAsync / validate", width=46, height=20, icon=PhosphorIcon.PLAY_CIRCLE, icon_size=6.5, card_style=Styles.PrimaryNeutral),
    xy=(28.0, 52.0),
)
codec_exec = exec_grp.add(
    Node("Bidirectional Codec API\ndecode / encode\nsafeDecode / safeEncode", width=46, height=20, icon=PhosphorIcon.ARROWS_LEFT_RIGHT, icon_size=6.5, card_style=Styles.Neutral),
    xy=(28.0, 15.0),
)

# Center Group: Core Schema & Error Engine (node width=40 -> center x = 5 + 20 = 25)
core_grp = d.add(
    NodeGroup(title="2. Core Schema & $ZodError", padding=5.0),
    xy=(66.0, 0.0),
)
schema_hub = core_grp.add(
    Node("ZodType<O, I>\n_zod.run(payload, ctx)\nz.infer / z.input / z.output", width=40, height=20, icon=PhosphorIcon.CUBE, icon_size=6.5, style=Styles.WhiteBold, card_style=Styles.PrimaryFlat, text_style=Styles.WhiteBold.patch(text_size=10.0)),
    xy=(25.0, 52.0),
)
err_hub = core_grp.add(
    Node("ZodError & Formatters\nprettifyError / treeifyError\nflattenError / formatError", width=40, height=20, icon=PhosphorIcon.WARNING_OCTAGON, icon_size=6.5, style=Styles.WhiteBold, card_style=Styles.AccentFlat, text_style=Styles.WhiteBold.patch(text_size=10.0)),
    xy=(25.0, 15.0),
)

# Right Group: Registries & JSON Schema (node width=46 -> center x = 5 + 23 = 28)
meta_grp = d.add(
    NodeGroup(title="3. Registries & JSON Schema", padding=5.0),
    xy=(126.0, 0.0),
)
reg_node = meta_grp.add(
    Node("Metadata Registries\n$ZodRegistry<Meta>\nz.globalRegistry / .meta()", width=46, height=20, icon=PhosphorIcon.BOOKMARK_SIMPLE, icon_size=6.5, card_style=Styles.Neutral),
    xy=(28.0, 52.0),
)
json_node = meta_grp.add(
    Node("JSON Schema Bridge\nz.toJSONSchema(schema)\nz.fromJSONSchema(json)", width=46, height=20, icon=PhosphorIcon.FILE_CODE, icon_size=6.5, card_style=Styles.PrimaryNeutral),
    xy=(28.0, 15.0),
)

# Connections
d.connect(parse_node, schema_hub, padding=1.5)
d.connect(codec_exec, schema_hub, padding=1.5)
d.connect(schema_hub, err_hub, label="issues[]", padding=1.5)
schema_hub.fork([reg_node, json_node], at_x=119.0, padding=1.5)
d.connect(reg_node, json_node, label="metadata", padding=1.5)

d.draw(xy=(94.0, 46.0), align="center")
canvas.save()

functionz.parse / z.safeParse / z.parseAsync / z.safeParseAsync#

Zod v4 exposes both standalone functions (z.parse(schema, data), z.safeParse(schema, data), z.validate(schema, data)) and instance methods (schema.parse(data), schema.safeParse(data), schema.validate(data)).

Parse & Type-Guard Execution Signatures#

ParseContext Options (ParseContext)#

import * as z from "zod";

const UserSchema = z.object({
  id: z.uuid(),
  email: z.email(),
});

// 1. Safe parsing with discriminated result
const res = z.safeParse(UserSchema, rawPayload, { reportInput: true });
if (!res.success) {
  console.error(z.prettifyError(res.error));
} else {
  console.log(res.data.email);
}

// 2. Boolean type guard via z.validate()
if (z.validate(UserSchema, rawPayload)) {
  // rawPayload is narrowed to z.input<typeof UserSchema>
  console.log(rawPayload.id);
}

functionz.encode / z.decode / z.safeEncode / z.safeDecode#

While parse always executes in the forward direction (Input -> Output), the codec execution family explicitly pairs forward decode (Input -> Output) with backward encode (Output -> Input).

Codec Execution Signatures#

classZodError & $ZodError#

Validation failures produce an instance of ZodError<T> (in zod, extending native Error) or $ZodError<T> (in zod/v4/core). Note that z.safeParse() uses a lazy getter on { success: false, get error() } so ZodError is only instantiated if .error is actually accessed.

Properties & Methods of ZodError<T>#

type$ZodIssue & Issue Subtypes#

Zod v4 consolidates issue codes into a clean 11-member discriminated union ($ZodIssue, keyed on issue.code), merging legacy v3 codes (invalid_string, invalid_ReturnValue, invalid_date, invalid_enum_value, invalid_literal) into unified structural types.

from drawlib import canvas
from drawlib.diagrams.class_diagram import ClassDiagram, ClassNode
from drawlib.fonts import FontRoboto, FontSourceCode
from drawlib.styles import Styles

canvas.clear()
canvas.setup(width=188, height=104, dpi=150)

cd = ClassDiagram(
    node_style=Styles.Neutral.patch(text_font=FontSourceCode.ROBOTO_MONO, text_size=9.5),
    header_style=Styles.PrimaryNeutral.patch(text_font=FontRoboto.ROBOTO_BOLD, text_size=10.5),
    edge_style=Styles.DarkBold,
    edge_text_style=Styles.Dark.patch(text_size=9.5),
    title="ZodIssue ($ZodIssueBase) — 11 Discriminated Issue Union Subtypes",
)

# Top Root Interface (ClassNode xy is Center!)
base_issue = cd.add(
    ClassNode("$ZodIssueBase", stereotype="interface", width=62, header_style=Styles.SecondaryNeutral.patch(text_font=FontRoboto.ROBOTO_BOLD, text_size=10.5))
    .add_attribute("code", "$ZodIssueCode", visibility="+")
    .add_attribute("path", "PropertyKey[]", visibility="+")
    .add_attribute("message", "string", visibility="+")
    .add_attribute("input", "unknown | undefined", visibility="+"),
    xy=(94.0, 74.0),
)

# Bottom Row 1: Type, Value & Custom Issues
grp_type = cd.add(
    ClassNode("Type, Value & Custom", width=44, header_style=Styles.PrimaryNeutral)
    .add_attribute("invalid_type", "{ expected }")
    .add_attribute("invalid_value", "{ values: Primitive[] }")
    .add_attribute("custom", "{ params?: Record }"),
    xy=(23.0, 22.0),
)

# Bottom Row 2: Range, Size & Divisibility Issues
grp_bounds = cd.add(
    ClassNode("Range & Divisibility", width=44, header_style=Styles.PrimaryNeutral)
    .add_attribute("too_big", "{ origin, maximum }")
    .add_attribute("too_small", "{ origin, minimum }")
    .add_attribute("not_multiple_of", "{ divisor: number }"),
    xy=(70.0, 22.0),
)

# Bottom Row 3: String Format & Object Key Issues
grp_format = cd.add(
    ClassNode("Format & Object Keys", width=44, header_style=Styles.PrimaryNeutral)
    .add_attribute("invalid_format", "{ format, pattern? }")
    .add_attribute("unrecognized_keys", "{ keys: string[] }"),
    xy=(117.0, 22.0),
)

# Bottom Row 4: Union & Collection Issues
grp_coll = cd.add(
    ClassNode("Union & Collections", width=44, header_style=Styles.PrimaryNeutral)
    .add_attribute("invalid_union", "{ errors, discriminator? }")
    .add_attribute("invalid_key", "{ origin, issues }")
    .add_attribute("invalid_element", "{ origin, key, issues }"),
    xy=(164.0, 22.0),
)

cd.connect(grp_type, base_issue, "inheritance", start_side="top", end_side="bottom")
cd.connect(grp_bounds, base_issue, "inheritance", start_side="top", end_side="bottom")
cd.connect(grp_format, base_issue, "inheritance", start_side="top", end_side="bottom")
cd.connect(grp_coll, base_issue, "inheritance", start_side="top", end_side="bottom")

cd.draw(xy=(94.0, 50.0), align="center")
canvas.save()

Complete $ZodIssue Union Reference#

functionz.prettifyError / z.treeifyError / z.flattenError / z.formatError#

Zod v4 provides four tree-shakable top-level error formatting functions that transform a $ZodError (or StandardSchemaV1.FailureResult) into human-readable strings or structured UI error trees.

Error Formatter Comparison#

import * as z from "zod";

const ProfileSchema = z.object({
  username: z.string().min(3),
  tags: z.array(z.string().min(2)),
});

const result = ProfileSchema.safeParse({ username: "ab", tags: ["ok", "x"] });
if (!result.success) {
  // 1. Human-readable CLI string
  console.log(z.prettifyError(result.error));
  // ✖ Too small: expected string to have >=3 characters
  //   → at username
  // ✖ Too small: expected string to have >=2 characters
  //   → at tags[1]

  // 2. Type-safe nested error tree
  const tree = z.treeifyError(result.error);
  console.log(tree.properties?.username?.errors); // ["Too small: ..."]
  console.log(tree.properties?.tags?.items?.[1]?.errors); // ["Too small: ..."]
}

functionz.config & z.locales#

Global runtime behavior and error message localization are managed through z.config(newConfig?) (backed by globalThis.__zod_globalConfig so CJS and ESM bundles share a single configuration instance) and z.locales.

$ZodConfig Options & Error Precedence#

import * as z from "zod";

// Switch default error messages to Japanese globally
z.config(z.locales.ja());

// Override specific issue codes globally while delegating others to the locale
z.config({
  customError: (issue) => {
    if (issue.code === "invalid_type" && issue.input === undefined) {
      return "Required field is missing";
    }
    return undefined; // Fall through to localeError
  },
});

class$ZodRegistry & z.globalRegistry#

Zod v4 decouples schema metadata from schema instances using WeakMap-backed $ZodRegistry<Meta, Schema> containers. Because registry entries are held in a WeakMap<Schema, Meta>, ephemeral schemas are garbage-collected normally while registered schemas with an id are also indexed for $defs extraction in z.toJSONSchema().

$ZodRegistry API & Schema Helpers#

[!TIP] Use the phantom symbols z.$output and z.$input inside a custom registry's Meta type to constrain metadata fields to the registered schema's static output or input type (e.g., z.registry<{ examples: z.$output[] }>()).

import * as z from "zod";

// Custom registry with type-safe examples tied to each schema's output type
const docRegistry = z.registry<{
  id?: string;
  title: string;
  examples: z.$output[];
}>();

const PortSchema = z.int().min(1).max(65535).register(docRegistry, {
  id: "PortNumber",
  title: "TCP/UDP Port",
  examples: [80, 443, 8080], // Statically checked as number[]!
});

functionz.toJSONSchema & z.fromJSONSchema#

Zod v4 ships native, zero-dependency bidirectional conversion between Zod schemas/registries and JSON Schema (draft-2020-12, draft-07, draft-04, and openapi-3.0).

z.toJSONSchema & z.fromJSONSchema Signatures#

ToJSONSchemaParams Options#

import * as z from "zod";

const UserSchema = z
  .object({
    id: z.uuid(),
    role: z.enum(["admin", "member"]).default("member"),
  })
  .meta({ id: "User", title: "Platform User" });

// Emit OpenAPI 3.0 input schema
const openApiInput = z.toJSONSchema(UserSchema, {
  target: "openapi-3.0",
  io: "input",
});

// Reconstruct a runtime Zod schema from a JSON Schema document
const DynamicValidator = z.fromJSONSchema(openApiInput);

typez.infer / z.input / z.output#

In Zod v4, z.input and z.output serve a dual role: they are static TypeScript type helpers (z.input<typeof S>, z.output<typeof S>, z.infer<typeof S>) AND runtime schema projection functions (z.input(schema), z.output(schema)).

Static Type & Runtime Schema Projection Reference#

import * as z from "zod";

const AccountCodec = z.object({
  createdAt: z.codec(z.iso.datetime(), z.date(), {
    decode: (s) => new Date(s),
    encode: (d) => d.toISOString(),
  }),
});

// 1. Static Type Extraction
type AccountWire = z.input<typeof AccountCodec>;   // { createdAt: string }
type AccountDomain = z.infer<typeof AccountCodec>; // { createdAt: Date }

// 2. Runtime Schema Projection (rewrites pipes/codecs to pure input or output schemas)
const WireOnlySchema = z.input(AccountCodec);     // Validates { createdAt: string } -> { createdAt: string }
const DomainOnlySchema = z.output(AccountCodec);  // Validates { createdAt: Date }   -> { createdAt: Date }