Zod Validation (v4)

Type-safe schema validation for TypeScript. Zod v4 introduces top-level format functions, z.stringbool(), z.iso.* date formats, z.overwrite() transforms, z.file(), z.toJSONSchema(), getter-based recursive types, .meta(), and the unified error function.

Package: zod (also zod/mini for smaller bundles)

Quick Reference

Pattern	Usage
`z.object({ ... })`	Define object schemas
`z.string()`, `z.number()`	Primitive types
`z.email()`, `z.url()`, `z.uuid()`	Top-level string formats (v4)
`z.iso.date()`, `z.iso.datetime()`	ISO date/time formats (v4)
`z.int()`, `z.float32()`, `z.int32()`	Fixed-width number formats (v4)
`z.templateLiteral([...])`	Template literal type validation (v4)
`z.enum([...])`, `z.literal()`	Enums and literals
`z.union([...])`, `z.discriminatedUnion()`	Union types
`z.array()`, `z.tuple()`	Array and tuple types
`z.record()`, `z.map()`	Key-value collections
`.optional()`, `.nullable()`	Optional and nullable modifiers
`.default()`, `.catch()`	Default values and fallbacks
`.prefault()`	Pre-parse default (parsed through schema, v4)
`z.coerce.number()`	Type coercion before validation
`z.stringbool()`	String-to-boolean parsing (v4)
`.transform()`, `.overwrite()`	Output transforms
`z.pipe()`	Chain schemas (output feeds next input)
`.refine()`, `.superRefine()`	Custom validation logic
`.parse()`, `.safeParse()`	Validate and extract data
`z.infer<typeof Schema>`	Extract TypeScript type from schema
`z.input<>`, `z.output<>`	Input vs output types with transforms
`z.file()`	File instance validation (v4)
`z.toJSONSchema()`	Convert schema to JSON Schema (v4)
`.meta()`, `.describe()`	Attach metadata to schemas (v4)
`z.prettifyError()`	Human-readable error formatting (v4)
`z.treeifyError()`	Structured error tree (replaces .format(), v4)
`z.registry()`	Typed schema registry (v4)
`{ error: (issue) => ... }`	Unified error customization (v4)
Getter-based recursion	Recursive types without `z.lazy()` (v4)
`z.globalRegistry`	Global schema metadata registry (v4)
`z.config(z.locales.en())`	Internationalized error messages (v4)

Common Mistakes

Mistake	Fix
`z.string().email()`	`z.email()` (v4 top-level format)
`z.string().url()`	`z.url()` (v4 top-level format)
Using `parse` without try/catch	Use `safeParse` for error handling
Forgetting `.optional()`	Add when field may be undefined
`z.any()` for unknown data	Use `z.unknown()` for type-safe unknown
`.transform()` for same-type changes	Use `.overwrite()` (introspectable, v4)
Missing `.min(1)` on strings	Empty strings pass `z.string()` by default
`z.number().parse(Infinity)`	`z.number()` rejects `Infinity` in v4
`z.number().safe()` for floats	`.safe()` equals `.int()` in v4 (no floats)
`z.lazy()` for recursive types	Use getter syntax in v4 (retains object methods)
`required_error` / `invalid_type_error`	Use unified `error` function in v4
`.refine(fn, (val) => ({ message }))`	Function-as-second-arg overload removed; use `.superRefine()`
`errorMap` on schemas	Replaced by `error` function in v4
`z.record(z.string())` single arg	v4 requires two args: `z.record(z.string(), z.string())`
`.format()` / `.flatten()` on ZodError	Deprecated; use `z.treeifyError(err)` in v4
`.default()` with input type value	v4 `.default()` uses output type; use `.prefault()` for input

Delegation

Use this skill for Zod schema definition, validation, parsing, type inference, coercion, error formatting, metadata, and JSON Schema conversion. For form integration, delegate to the tanstack-form skill.

References

Schema Types — primitives, string formats, number formats, template literals, objects, arrays, enums, unions, records, optional, nullable
Transforms and Parsing — coercion, stringbool, transforms, overwrite, pipe, refinements, parsing, type inference
Error Handling — unified error function, prettifyError, treeifyError, ZodError, error formatting, internationalization
Common Patterns — form validation, API responses, environment variables, schema composition, recursive types, branded types
Metadata and JSON Schema — meta, describe, globalRegistry, toJSONSchema, file validation, Zod Mini

zod-validation

Zod Validation (v4)

Quick Reference

Common Mistakes

Delegation

References