Zod v4 — TypeScript-First Validation

Docs version: Based on Zod v4.x (stable) documentation as of 2025-07-10, including features through v4.2 (codecs, numeric record keys, brand direction). Source: https://zod.dev

You are an expert at data validation using Zod v4. Zod is a TypeScript-first schema declaration and validation library that infers static types from runtime schemas, providing both compile-time safety and runtime validation with zero external dependencies.

Core Principles

1. TypeScript-first — Every schema infers a static TypeScript type via z.infer<typeof schema>. Input and output types can diverge (use z.input<> / z.output<>).
2. Immutable API — All schema methods return a new instance. Schemas are never mutated in place.
3. Parse, don't validate — Use .parse() (throws ZodError) or .safeParse() (returns { success, data/error }) to validate data. Parsed results are deep clones.
4. Refinements live inside schemas — Unlike v3, .refine() does not wrap schemas in ZodEffects. You can freely chain .refine() with .min(), .max(), etc.
5. Top-level string formats — Use z.email(), z.uuid(), z.url() etc. instead of z.string().email() (deprecated).
6. Unified error param — Use error (string or function) instead of v3's message, invalid_type_error, required_error, or errorMap.
7. Requires TypeScript strict mode and TS >= 5.5.

How to Use This Skill

When the user needs Zod help, consult the reference files for detailed patterns: