zod
pproenca/dot-skills
Zod schema validation best practices for type safety, parsing, and error handling.
What is zod?
Zod is a TypeScript-first schema validation library. Use this skill when defining z.object schemas, choosing between parse() and safeParse(), implementing type inference with z.infer, handling validation errors, or composing complex schemas. Does not cover React Hook Form or OpenAPI client generation.
- Define type-safe schemas with correct primitive types and validations
- Parse and validate user input safely with safeParse() and error handling
- Infer TypeScript types from schemas using z.infer and distinguish input vs output types
- Handle validation errors with custom messages, flattening, and nested path tracking
- Compose reusable schemas using extend(), intersection(), pick(), omit(), and lazy()
- Apply refinements, transforms, and coercions for data normalization and validation
How to install zod
npx skills add https://github.com/pproenca/dot-skills --skill zodHow to use zod
- 1.Install the skill with: npx skills add https://github.com/pproenca/dot-skills --skill zod
- 2.Review the 8 rule categories (Schema Definition, Parsing & Validation, Type Inference, Error Handling, Object Schemas, Schema Composition, Refinements & Transforms, Performance & Bundle)
- 3.Reference individual rule files for detailed explanations and code examples when writing schemas
- 4.Use safeParse() for user input and parse() only for trusted data
- 5.Apply z.infer to extract TypeScript types from your schemas instead of writing manual types
- 6.Use flatten() for form error display and issue.path for nested error locations
- 7.Cache schema instances and avoid dynamic schema creation in performance-critical paths
Use cases
- Validating form submissions and user input at API boundaries
- Parsing and type-checking JSON responses from external APIs
- Creating reusable schema modules for domain models across your application
- Implementing custom error messages and internationalized validation feedback
- Building discriminated unions for type-safe data handling in complex domains
- TypeScript developers building type-safe applications
- Backend engineers validating API requests and responses
- Full-stack developers managing shared schemas across client and server
- Teams implementing form validation with custom error handling
- Developers working with complex domain models requiring schema composition
zod FAQ
Use safeParse() for all user input and untrusted data—it returns a result object with success/error. Use parse() only for data you control and trust, as it throws on validation failure.
Use z.infer<typeof mySchema> to extract the output type. For distinguishing input from output types (when using transforms), use z.input<typeof mySchema> for the input type.
optional() allows undefined (field can be omitted), while nullable() allows null (field must be present but can be null). Use optional() for form fields that may not be submitted.
Use error.flatten() to restructure validation errors by field path, making it easy to map errors to form inputs. Access nested errors with issue.path for deeply nested objects.
Use strict() to reject unknown properties (safer for APIs), or strip() to silently remove them (better for form data). Choose based on whether unknown fields should be an error or ignored.
Full instructions (SKILL.md)
Source of truth, from pproenca/dot-skills.
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:
- Section definitions - Category structure and impact levels
- Rule template - Template for adding new rules
- Individual rules:
references/{prefix}-{slug}.md
Full Compiled Document
For the complete guide with all rules expanded: AGENTS.md
Related Skills
- For React Hook Form integration, see
react-hook-formskill - For API client generation, see
orvalskill
Sources
Related skills
More from pproenca/dot-skills and the wider catalog.
emilkowal-animations
Emil Kowalski's animation best practices for React, CSS, and Framer Motion.
clean-architecture
Clean Architecture principles and best practices for designing maintainable, testable software systems.
react-hook-form
Performance optimization guide for React Hook Form client-side forms with 45 rules across 8 categories.
vitest
Vitest testing framework patterns for test setup, async testing, mocking with vi.*, snapshots, and test performance (formerly test-vitest). This skill should be used when writing or debugging Vitest tests. This skill does NOT cover TDD methodology (use test-tdd skill), API mocking with MSW (use test-msw skill), or Jest-specific APIs.
nuqs
nuqs (type-safe URL query state) best practices for Next.js and other React frameworks. This skill should be used when writing, reviewing, or refactoring code that uses nuqs for URL state management. Triggers on tasks involving useQueryState, useQueryStates, search params, URL state, query parameters, nuqs parsers, limitUrlUpdates, Standard Schema, NuqsAdapter, or Next.js routing with state.
code-simplifier
Code simplification skill for improving clarity, consistency, and maintainability while preserving exact behavior. Use when simplifying code, reducing complexity, cleaning up recent changes, applying refactoring patterns, or improving readability. Triggers on tasks involving code cleanup, simplification, refactoring, or readability improvements.