Zod Schema Validation Patterns

Quick Guide: Use Zod for runtime validation at trust boundaries (API responses, form inputs, config, URL params). Define schemas once, derive types with z.infer. Use safeParse for error handling, refine/superRefine for custom validation, transform for data conversion. Named constants for all validation limits.

Version Note: Zod v4 is now the stable release (v4.1+). It brings 14.7x faster string parsing, 57% smaller bundle, and new top-level APIs (z.email(), z.url(), z.iso.*). The v3 method-chain equivalents (z.string().email()) still work but are deprecated. For migration details, see reference.md.

<critical_requirements>

CRITICAL: Before Using This Skill

All code must follow project conventions in CLAUDE.md (kebab-case, named exports, import ordering, import type, named constants)

(You MUST use safeParse instead of parse for user-facing validation - prevents unhandled exceptions)

(You MUST use z.infer<typeof schema> to derive types - never duplicate schema as separate interface)

(You MUST validate at trust boundaries - API responses, form inputs, config files, URL params)