Zod schema validation best practices for type safety, parsing, and error handling. This skill should be used when defining z.object schemas, using z.string validations, safeParse, or z.infer. This skill does NOT cover React Hook Form integration patterns (use react-hook-form skill) or OpenAPI client generation (use orval skill).
Comprehensive schema validation guide for Zod in TypeScript applications. Contains 43 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.
Reference these guidelines when:
| Priority | Category | Impact | Prefix |
|---|---|---|---|
| 1 | Schema Definition | CRITICAL | schema- |
| 2 | Parsing & Validation | CRITICAL | parse- |
| 3 | Type Inference | HIGH | type- |
| 4 | Error Handling | HIGH | error- |
| 5 | Object Schemas | MEDIUM-HIGH | object- |
| 6 | Schema Composition | MEDIUM | compose- |
| 7 | Refinements & Transforms | MEDIUM | refine- |
| 8 | Performance & Bundle | LOW-MEDIUM | perf- |
schema-use-primitives-correctly - Use correct primitive schemas for each typeschema-use-unknown-not-any - Use z.unknown() instead of z.any() for type safetyschema-avoid-optional-abuse - Avoid overusing optional fieldsschema-string-validations - Apply string validations at schema definitionschema-use-enums - Use enums for fixed string valuesschema-coercion-for-form-data - Use coercion for form and query dataparse-use-safeparse - Use safeParse() for user inputparse-async-for-async-refinements - Use parseAsync for async refinementsparse-handle-all-issues - Handle all validation issues not just firstparse-validate-early - Validate at system boundariesparse-avoid-double-validation - Avoid validating same data twiceparse-never-trust-json - Never trust JSON.parse outputtype-use-z-infer - Use z.infer instead of manual typestype-input-vs-output - Distinguish z.input from z.infer for transformstype-export-schemas-and-types - Export both schemas and inferred typestype-branded-types - Use branded types for domain safetytype-enable-strict-mode - Enable TypeScript strict modeerror-custom-messages - Provide custom error messageserror-use-flatten - Use flatten() for form error displayerror-path-for-nested - Use issue.path for nested error locationerror-i18n - Implement internationalized error messageserror-avoid-throwing-in-refine - Return false instead of throwing in refineobject-strict-vs-strip - Choose strict() vs strip() for unknown keysobject-partial-for-updates - Use partial() for update schemasobject-pick-omit - Use pick() and omit() for schema variantsobject-extend-for-composition - Use extend() for adding fieldsobject-optional-vs-nullable - Distinguish optional() from nullable()object-discriminated-unions - Use discriminated unions for type narrowingcompose-shared-schemas - Extract shared schemas into reusable modulescompose-intersection - Use intersection() for type combinationscompose-lazy-recursive - Use z.lazy() for recursive schemascompose-preprocess - Use preprocess() for data normalizationcompose-pipe - Use pipe() for multi-stage validationrefine-vs-superrefine - Choose refine() vs superRefine() correctlyrefine-transform-coerce - Distinguish transform() from refine() and coerce()refine-add-path - Add path to refinement errorsrefine-defaults - Use default() for optional fields with defaultsrefine-catch - Use catch() for fault-tolerant parsingperf-cache-schemas - Cache schema instancesperf-zod-mini - Use Zod Mini for bundle-sensitive applicationsperf-avoid-dynamic-creation - Avoid dynamic schema creation in hot pathsperf-lazy-loading - Lazy load large schemasperf-arrays - Optimize large array validationRead individual reference files for detailed explanations and code examples:
references/{prefix}-{slug}.mdFor the complete guide with all rules expanded: AGENTS.md
react-hook-form skillorval skill