| name | zod |
| description | 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). |
Zod Best Practices
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.
When to Apply
Reference these guidelines when:
- Writing new Zod schemas
- Choosing between parse() and safeParse()
- Implementing type inference with z.infer
- Handling validation errors for user feedback
- Composing complex object schemas
- Using refinements and transforms
- Optimizing bundle size and validation performance
- Reviewing Zod code for best practices
Rule Categories by Priority
| 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- |
Quick Reference
1. Schema Definition (CRITICAL)
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 data
2. Parsing & Validation (CRITICAL)
parse-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 output
3. Type Inference (HIGH)
type-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 mode
4. Error Handling (HIGH)
error-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 refine
5. Object Schemas (MEDIUM-HIGH)
object-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 narrowing
6. Schema Composition (MEDIUM)
compose-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 validation
7. Refinements & Transforms (MEDIUM)
refine-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 parsing
8. Performance & Bundle (LOW-MEDIUM)
perf-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 validation
How to Use
Read individual reference files for detailed explanations and code examples:
Full Compiled Document
For the complete guide with all rules expanded: AGENTS.md
Related Skills
- For React Hook Form integration, see
react-hook-form skill
- For API client generation, see
orval skill
Sources
