Zod

IMPORTANT: Your training data about zod may be outdated or incorrect — Zod 4 changes string formats, enums, error customization, issue codes, defaults, and functions. Always rely on this skill's rule files and the project's actual source code as the source of truth. Do not fall back on memorized v3 patterns when they conflict with the retrieved reference.

When to Use Zod

Zod is for runtime type validation — parsing untrusted data at system boundaries (API input, form data, env vars, external services). For compile-time-only types, plain TypeScript is sufficient.

Rule Categories by Priority

Quick Reference

1. Parsing & Type Safety (CRITICAL)

• parse-use-safeParse — Use safeParse() for user input instead of parse() which throws
• parse-async-required — Must use parseAsync()/safeParseAsync() when schema has async refinements
• parse-infer-types — Use z.infer<typeof Schema> for output types; never manually duplicate types
• parse-validate-boolean — Use .validate() for a yes or no; it narrows to the input type, so use safeParse() for the output

2. Schema Design (CRITICAL)

• schema-object-unknowns — z.object() strips unknown keys; use strictObject or looseObject
• schema-union-discriminated — Use z.discriminatedUnion() for tagged unions, not z.union()
• schema-coercion-pitfalls — z.coerce.boolean() makes "false" → true; use z.stringbool()
• schema-recursive-types — Use a getter for recursive schemas; cyclic input parses since 4.5
• schema-json-string — z.json() does not parse a string; decode JSON text with a codec

3. Refinements & Transforms (HIGH)

• refine-never-throw — Never throw inside .refine() or .transform(); return false, or add issues through ctx
• refine-vs-transform — .refine() for validation, .transform() for conversion, .pipe() for staging
• refine-cross-field — Refine the parent object and set path; .superRefine() for several issues

4. Error Handling (HIGH)

• error-custom-messages — Use the error parameter; required_error/invalid_type_error are gone, message is deprecated
• error-formatting — z.flattenError() for forms, z.treeifyError() for nested; formatError deprecated
• error-input-security — Never use reportInput: true in production; leaks sensitive data

5. Performance & Composition (MEDIUM)

• perf-extend-spread — Use { ...Schema.shape } spread over chained .extend() for large schemas
• perf-reuse-schemas — Define once, derive with .pick(), .omit(), .partial()
• perf-zod-mini — Use Zod Mini (zod/mini) only under a strict client bundle budget; load a locale
• perf-compile — Compile the final schema with z.compile(); prove it compiled with strict: true in a test

6. v4 Migration (MEDIUM)

• migrate-string-formats — Use z.email(), z.uuid(), z.url() not z.string().email()
• migrate-native-enum — Use unified z.enum() for TS enums; z.nativeEnum() is deprecated
• migrate-error-api — Use the error parameter; errorMap is gone and message is deprecated

7. Advanced Patterns (MEDIUM)

• pattern-branded-types — .brand<"Name">() for nominal typing (USD vs EUR)
• pattern-codecs — z.codec() for bidirectional transforms (parse + serialize)
• pattern-pipe — .pipe() for staged parsing (string → number → validate range)

8. Architecture & Boundaries (CRITICAL/HIGH)

• arch-boundary-parsing — Parse at system boundaries (API handler, env, form, fetch); pass typed data to domain logic
• arch-schema-organization — Co-locate schemas with their boundary layer; domain types use z.infer
• arch-schema-versioning — Additive changes only for non-breaking evolution; new fields use .optional()

9. Observability (HIGH/MEDIUM)

• observe-structured-errors — Use z.flattenError() for compact structured logs with request correlation IDs
• observe-error-metrics — trackedSafeParse() wrapper to increment counters per schema and field on failure

Schema Types Quick Reference

How to Use

Read individual rule files for detailed explanations and code examples:

rules/parse-use-safeParse.md
rules/schema-object-unknowns.md

Each rule file contains:

• Brief explanation of why it matters
• Incorrect code example with explanation
• Correct code example with explanation
• Additional context and decision tables

References

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md