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