2. Objects, Collections, Unions & Wrapper Combinators

This module documents Zod v4.6.7's composite container schemas (ZodObject, ZodArray, ZodTuple, ZodRecord, ZodMap, ZodSet), algebraic union and intersection combinators (ZodUnion, ZodXor, ZodDiscriminatedUnion, ZodIntersection), wrapper modifiers (ZodOptional, ZodExactOptional, ZodNullable, ZodDefault, ZodPrefault, ZodNonOptional, ZodCatch, ZodReadonly, $ZodBranded), recursive/custom schemas (z.lazy, z.custom, z.instanceof, z.json), and runtime function/promise wrappers (ZodFunction, ZodPromise).

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

canvas.clear()
canvas.setup(width=184, height=106, dpi=150)

text(
    (92, 100.5),
    "Zod v4.6.7 Composite Schemas Hierarchy (Objects, Collections & Unions)",
    style=Styles.DarkBold.patch(text_size=13.0),
)

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

# Root Base Class
root = d.add(
    Node(
        "ZodType<Output, Input>  (Container Base + Memoized Shape Resolution)\nparse / safeParse / check / toJSONSchema / ~standard",
        width=102,
        height=12.5,
        icon=PhosphorIcon.CUBE,
        icon_size=5.8,
        style=Styles.WhiteBold,
        text_style=Styles.WhiteBold.patch(text_size=10.5),
        card_style=Styles.PrimaryFlat,
    ),
    xy=(88.0, 84.0),
)

# Group 1: Object Schemas
g_obj = d.add(
    NodeGroup(title="Object Schemas ($ZodObjectJIT)", padding=4.5),
    xy=(2.0, 4.0),
)
g_obj.add(
    Node("ZodObject ($strip)\nz.object(shape)", width=46, height=12.5, icon=PhosphorIcon.BRACKETS_CURLY, icon_size=5.5, style=Styles.WhiteBold, text_style=Styles.WhiteBold.patch(text_size=10.0), card_style=Styles.AccentFlat),
    xy=(27.5, 49.0),
)
g_obj.add(
    Node("z.strictObject(shape)\ncatchall: z.never()", width=46, height=12.5, icon=PhosphorIcon.LOCK_KEY, icon_size=5.5, card_style=Styles.PrimaryNeutral),
    xy=(27.5, 34.0),
)
g_obj.add(
    Node("z.looseObject(shape)\ncatchall: z.unknown()", width=46, height=12.5, icon=PhosphorIcon.ARROWS_OUT_SIMPLE, icon_size=5.5, card_style=Styles.Neutral),
    xy=(27.5, 19.0),
)
g_obj.add(
    Node("Shape Combinators\nextend / pick / omit / partial", width=46, height=12.5, icon=PhosphorIcon.SLIDERS, icon_size=5.5, card_style=Styles.Neutral),
    xy=(27.5, 4.0),
)

# Group 2: Collection Schemas
g_col = d.add(
    NodeGroup(title="Collection & Key-Value Schemas", padding=4.5),
    xy=(61.0, 4.0),
)
g_col.add(
    Node("ZodArray<T>\nz.array(el) / min / max", width=48, height=12.5, icon=PhosphorIcon.BRACKETS_SQUARE, icon_size=5.5, card_style=Styles.PrimaryNeutral),
    xy=(28.5, 49.0),
)
g_col.add(
    Node("ZodTuple<T, Rest>\nz.tuple([...], rest?)", width=48, height=12.5, icon=PhosphorIcon.LIST_NUMBERS, icon_size=5.5, card_style=Styles.Neutral),
    xy=(28.5, 34.0),
)
g_col.add(
    Node("ZodRecord<K, V>\nrecord / partial / loose", width=48, height=12.5, icon=PhosphorIcon.TABLE, icon_size=5.5, card_style=Styles.Neutral),
    xy=(28.5, 19.0),
)
g_col.add(
    Node("ZodMap & ZodSet\nz.map(k, v) / z.set(v)", width=48, height=12.5, icon=PhosphorIcon.STACK, icon_size=5.5, card_style=Styles.Neutral),
    xy=(28.5, 4.0),
)

# Group 3: Unions & Intersections
g_uni = d.add(
    NodeGroup(title="Algebraic Unions & Intersections", padding=4.5),
    xy=(122.0, 4.0),
)
g_uni.add(
    Node("ZodUnion<Options>\nz.union([...]) / .or()", width=46, height=12.5, icon=PhosphorIcon.GIT_FORK, icon_size=5.5, card_style=Styles.PrimaryNeutral),
    xy=(27.5, 49.0),
)
g_uni.add(
    Node("ZodDiscriminatedUnion\nz.discriminatedUnion(d, opts)", width=46, height=12.5, icon=PhosphorIcon.LIGHTNING, icon_size=5.5, card_style=Styles.PrimaryNeutral),
    xy=(27.5, 34.0),
)
g_uni.add(
    Node("ZodXor<Options>\nz.xor([...]) (Exactly 1)", width=46, height=12.5, icon=PhosphorIcon.SPLIT_HORIZONTAL, icon_size=5.5, card_style=Styles.SecondaryNeutral),
    xy=(27.5, 19.0),
)
g_uni.add(
    Node("ZodIntersection<A, B>\nz.intersection(a, b) / .and()", width=46, height=12.5, icon=PhosphorIcon.INTERSECT, icon_size=5.5, card_style=Styles.Neutral),
    xy=(27.5, 4.0),
)

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

# Top-down tree bus from ZodType root (center x=92, bottom y=79.5) to the top of each group (y=68.5)
line((92.0, 79.5), (92.0, 74.5), style=Styles.PrimaryBold)
line((33.5, 74.5), (153.5, 74.5), style=Styles.PrimaryBold)
line((33.5, 74.5), (33.5, 68.5), arrow_head="->", style=Styles.PrimaryBold)
line((93.5, 74.5), (93.5, 68.5), arrow_head="->", style=Styles.PrimaryBold)
line((153.5, 74.5), (153.5, 68.5), arrow_head="->", style=Styles.PrimaryBold)

canvas.save()

classZodObject#

ZodObject<Shape, Config> validates JavaScript plain objects against a property Shape map (Record<string, $ZodType>). In Zod v4, object parsing uses a lazy property descriptor for .shape and optional fast-path JIT compilation ($ZodObjectJIT).

interface ZodObject<
  out Shape extends core.$ZodShape = core.$ZodLooseShape,
  out Config extends core.$ZodObjectConfig = core.$strip,
> extends _ZodType<core.$ZodObjectInternals<Shape, Config>>, core.$ZodObject<Shape, Config>

import { z } from "zod";

const BaseUser = z.object({
  id: z.uuid(),
  email: z.email(),
  name: z.string(),
});

// Extend, pick, omit, and partial combinators
const AdminUser = BaseUser.extend({ permissions: z.array(z.string()) });
const PublicProfile = BaseUser.omit({ email: true });
const PatchUser = BaseUser.partial({ name: true, email: true });

functionz.object / z.strictObject / z.looseObject#

Zod v4 provides three dedicated top-level object constructors corresponding to the three unrecognized-key policies:

function z.object<T extends core.$ZodLooseShape>(shape?: T, params?: string | core.$ZodObjectParams): ZodObject<util.Writeable<T>, core.$strip>
function z.strictObject<T extends core.$ZodLooseShape>(shape: T, params?: string | core.$ZodObjectParams): ZodObject<util.Writeable<T>, core.$strict>
function z.looseObject<T extends core.$ZodLooseShape>(shape: T, params?: string | core.$ZodObjectParams): ZodObject<util.Writeable<T>, core.$loose>

import { z } from "zod";

const StrictPayload = z.strictObject({ action: z.literal("login") });
StrictPayload.safeParse({ action: "login", extra: 123 }).success; // => false (unrecognized_keys)

const LoosePayload = z.looseObject({ action: z.literal("login") });
LoosePayload.parse({ action: "login", traceId: "abc" }); // => { action: "login", traceId: "abc" }

classZodArray#

Constructs a ZodArray<T> schema validating Array.isArray(input) and parsing every element against element: T.

function z.array<T extends core.SomeType>(element: T, params?: string | core.$ZodArrayParams): ZodArray<T>

import { z } from "zod";

const Tags = z.array(z.string().min(1)).min(1).max(10);

classZodTuple#

Constructs a fixed-length ZodTuple<T, Rest> schema with per-index schemas and an optional variadic rest element schema.

function z.tuple<T extends readonly [core.SomeType, ...core.SomeType[]]>(items: T, params?: string | core.$ZodTupleParams): ZodTuple<T, null>
function z.tuple<T extends readonly [core.SomeType, ...core.SomeType[]], Rest extends core.SomeType>(
  items: T,
  rest: Rest,
  params?: string | core.$ZodTupleParams
): ZodTuple<T, Rest>

import { z } from "zod";

const Coordinate = z.tuple([z.number(), z.number()], z.string());
type Coord = z.infer<typeof Coordinate>; // [number, number, ...string[]]

classZodRecord#

Constructs a ZodRecord<Key, Value> schema for key-value dictionary objects. Zod v4 distinguishes exhaustive records (z.record), partial enum/union key records (z.partialRecord), and pass-through records (z.looseRecord).

function z.record<Key extends core.$ZodRecordKey, Value extends core.SomeType>(
  keyType: Key,
  valueType: Value,
  params?: string | core.$ZodRecordParams
): ZodRecord<Key, Value>
function z.partialRecord<Key extends core.$ZodRecordKey, Value extends core.SomeType>(
  keyType: Key,
  valueType: Value,
  params?: string | core.$ZodRecordParams
): ZodRecord<Key & core.$partial, Value>
function z.looseRecord<Key extends core.$ZodRecordKey, Value extends core.SomeType>(
  keyType: Key,
  valueType: Value,
  params?: string | core.$ZodRecordParams
): ZodRecord<Key, Value>

import { z } from "zod";

const EnvMap = z.record(z.string(), z.string());
const LocaleOverrides = z.partialRecord(z.enum(["en", "ja", "de"]), z.string());

classZodMap & ZodSet#

Validates native ES6 Map<K, V> and Set<T> instances with built-in .size constraints.

function z.map<Key extends core.SomeType, Value extends core.SomeType>(
  keyType: Key,
  valueType: Value,
  params?: string | core.$ZodMapParams
): ZodMap<Key, Value>
function z.set<Value extends core.SomeType>(
  valueType: Value,
  params?: string | core.$ZodSetParams
): ZodSet<Value>

import { z } from "zod";

const UniqueIds = z.set(z.uuid()).nonempty().max(100);

classZodUnion & ZodXor#

z.union(options) constructs an inclusive OR union (A | B, succeeding on the first matching branch), while z.xor(options) constructs an exclusive XOR union that succeeds if and only if exactly one branch matches the input.

function z.union<const T extends readonly core.SomeType[]>(options: T, params?: string | core.$ZodUnionParams): ZodUnion<T>
function z.xor<const T extends readonly core.SomeType[]>(options: T, params?: string | core.$ZodXorParams): ZodXor<T>

import { z } from "zod";

// Exclusive union: must contain EITHER `id` OR `slug`, not both
const LookupFilter = z.xor([
  z.strictObject({ id: z.uuid() }),
  z.strictObject({ slug: z.string() }),
]);

classZodDiscriminatedUnion#

Constructs an O(1) lookup union indexed by a shared discriminator property (discriminator: Disc). In Zod v4, z.discriminatedUnion supports nested discriminated unions, pipes, and multi-value literals as discriminator values.

function z.discriminatedUnion<
  Types extends readonly [core.$ZodTypeDiscriminable, ...core.$ZodTypeDiscriminable[]],
  Disc extends string,
>(
  discriminator: Disc,
  options: Types,
  params?: string | core.$ZodDiscriminatedUnionParams
): ZodDiscriminatedUnion<Types, Disc>

import { z } from "zod";

const WebhookEvent = z.discriminatedUnion("type", [
  z.object({ type: z.literal("invoice.paid"), amount: z.int() }),
  z.object({ type: z.literal("invoice.failed"), reason: z.string() }),
]);

classZodIntersection#

Constructs a logical AND intersection (A & B) that parses input through both left and right schemas and deeply merges their outputs (z.intersection(a, b) or a.and(b)).

function z.intersection<T extends core.SomeType, U extends core.SomeType>(left: T, right: U): ZodIntersection<T, U>

[!TIP] For combining two ZodObject schemas, prefer A.extend(B.shape) over z.intersection(A, B) — .extend() produces a flat ZodObject that supports .keyof(), .pick(), .omit(), and fast JIT object compilation.

classZodOptional & ZodNullable#

Wrapper combinators modify how undefined, null, default values, and parse failures flow into and out of an inner schema T.

from drawlib import canvas
from drawlib.diagrams.flow import Decision, FlowDiagram, Process, Start
from drawlib.styles import Styles
from drawlib.text import text

canvas.clear()
canvas.setup(width=184, height=84, dpi=150)

text(
    (92, 79.0),
    "Zod v4 Wrapper Combinator Execution Flow (Prefault vs Default & Catch)",
    style=Styles.DarkBold.patch(text_size=12.5),
)

flow = FlowDiagram(
    node_style=Styles.Neutral,
    edge_style=Styles.PrimaryBold,
    edge_text_style=Styles.DarkBold.patch(text_size=10.0),
)

n_in = flow.add(
    Start(
        "Raw Input (data)\nparse(data)",
        width=28,
        height=12,
        style=Styles.PrimaryFlat,
        text_style=Styles.WhiteBold.patch(text_size=10.0),
    ),
    xy=(16.0, 42.0),
)

d_undef = flow.add(
    Decision(
        "data ===\nundefined?",
        width=28,
        height=16,
        style=Styles.PrimaryNeutral,
        text_style=Styles.DarkBold.patch(text_size=10.0),
    ),
    xy=(54.0, 42.0),
)

n_default = flow.add(
    Process(
        "ZodDefault / ZodOptional\nShort-circuits inner parse!\nReturns defaultValue / undefined",
        width=48,
        height=14,
        style=Styles.SecondaryNeutral,
        text_style=Styles.DarkBold.patch(text_size=10.0),
    ),
    xy=(104.0, 62.0),
)

n_prefault = flow.add(
    Process(
        "ZodPrefault(initVal)\nSubstitutes data = initVal\nand runs innerType!",
        width=44,
        height=14,
        style=Styles.PrimaryNeutral,
        text_style=Styles.DarkBold.patch(text_size=10.0),
    ),
    xy=(54.0, 12.0),
)

n_inner = flow.add(
    Process(
        "Inner Schema (innerType)\nValidates & Transforms\n(or ZodNullable if null)",
        width=48,
        height=14,
        style=Styles.Neutral,
        text_style=Styles.DarkBold.patch(text_size=10.0),
    ),
    xy=(104.0, 32.0),
)

n_out = flow.add(
    Process(
        "ZodCatch / ZodReadonly\nOn error -> catchValue(ctx)\nOn ok -> Object.freeze / $brand",
        width=44,
        height=16,
        style=Styles.AccentFlat,
        text_style=Styles.WhiteBold.patch(text_size=10.0),
    ),
    xy=(156.0, 46.0),
)

flow.connect(n_in, d_undef)
flow.connect(d_undef, n_default, label="Yes (default)", start_side="top", end_side="left")
flow.connect(d_undef, n_prefault, label="Yes (prefault)", start_side="bottom", end_side="top")
flow.connect(d_undef, n_inner, label="No", start_side="right", end_side="left")
flow.connect(n_prefault, n_inner, start_side="right", end_side="bottom")
flow.connect(n_default, n_out, start_side="right", end_side="top")
flow.connect(n_inner, n_out, start_side="right", end_side="bottom")

flow.draw(xy=(2.0, 2.0))
canvas.save()

function z.optional<T extends core.SomeType>(innerType: T): ZodOptional<T>
function z.exactOptional<T extends core.SomeType>(innerType: T): ZodExactOptional<T>
function z.nullable<T extends core.SomeType>(innerType: T): ZodNullable<T>
function z.nullish<T extends core.SomeType>(innerType: T): ZodOptional<ZodNullable<T>>
function z.nonoptional<T extends core.SomeType>(innerType: T, params?: string | core.$ZodNonOptionalParams): ZodNonOptional<T>

classZodDefault & ZodPrefault#

Zod v4 provides both output-side short-circuit defaults (ZodDefault) and input-side pre-parse defaults (ZodPrefault):

function z._default<T extends core.SomeType>(
  innerType: T,
  defaultValue: util.NoUndefined<core.output<T>> | (() => util.NoUndefined<core.output<T>>)
): ZodDefault<T>
function z.prefault<T extends core.SomeType>(
  innerType: T,
  defaultValue: core.input<T> | (() => core.input<T>)
): ZodPrefault<T>

import { z } from "zod";

const TrimmedWithDefault = z.string().trim().default("guest");
TrimmedWithDefault.parse(undefined); // => "guest" (short-circuited)

const TrimmedWithPrefault = z.string().trim().prefault("  guest  ");
TrimmedWithPrefault.parse(undefined); // => "guest" (parsed & trimmed through innerType!)

classZodCatch & ZodReadonly#

Error-recovery (ZodCatch), boolean success coercion (ZodSuccess), deep/shallow immutability (ZodReadonly), and nominal type branding ($ZodBranded):

function z.catch<T extends core.SomeType>(
  innerType: T,
  catchValue: core.output<T> | ((ctx: core.$ZodCatchCtx) => core.output<T>)
): ZodCatch<T>
function z.readonly<T extends core.SomeType>(innerType: T): ZodReadonly<T>
function z.success<T extends core.SomeType>(innerType: T): ZodSuccess<T>

import { z } from "zod";

const SafeRetryCount = z.int().min(0).catch((ctx) => {
  console.warn("Invalid retry count, falling back to 3:", ctx.error.issues);
  return 3;
});

const UserId = z.uuid().brand<"UserId">();
type UserId = z.infer<typeof UserId>; // string & z.$brand<"UserId">

functionz.lazy & z.custom#

Recursive schemas (z.lazy), arbitrary TypeScript type predicates (z.custom), class instance checks (z.instanceof), and recursive JSON value schemas (z.json).

[!TIP] Native Recursive Objects in Zod v4: You no longer need z.lazy() for most recursive objects and arrays! Using a getter property inside z.object({ get subcategories() { return z.array(Category); } }) preserves full static type inference without manual z.ZodType annotations. Use z.lazy(() => ...) when defining top-level mutually recursive unions or aliases.

function z.lazy<T extends core.SomeType>(getter: () => T): ZodLazy<T>
function z.custom<O>(fn?: (data: unknown) => unknown, params?: string | core.$ZodCustomParams): ZodCustom<O, O>
function z.instanceof<T extends typeof util.Class>(cls: T, params?: ZodInstanceOfParams): ZodInstanceOf<InstanceType<T>>
function z.json(params?: string | core.$ZodCustomParams): ZodJSONSchema

import { z } from "zod";

// Native getter recursion in Zod v4 (no z.lazy boilerplate needed)
const Category = z.object({
  name: z.string(),
  get children() {
    return z.array(Category);
  },
});

classZodFunction & ZodPromise#

z.function() constructs a runtime-validated function wrapper (ZodFunction<Args, Returns>) that validates incoming arguments and return values whenever the wrapped function is invoked. z.promise(schema) validates that an input is a Promise and parses its resolved value.

function z.function<In extends core.$ZodFunctionIn, Out extends core.$ZodType>(params?: {
  input?: In | ReadonlyArray<core.$ZodType>;
  output?: Out;
}): ZodFunction<In, Out>
function z.promise<T extends core.SomeType>(innerType: T): ZodPromise<T>

import { z } from "zod";

const ComputeTax = z.function({
  input: [z.number().nonnegative(), z.number().min(0).max(1)],
  output: z.number().nonnegative(),
});

const calc = ComputeTax.implement((amount, rate) => amount * rate);
calc(100, 0.08); // => 8