designing-zod-schemas
Designs Zod schemas following Zod-first development. Creates validation schemas, branded types, discriminated unions, and transforms. Infers TypeScript types from schemas. Triggers on: Zod schema, z.object, z.infer, validation, branded types, discriminated union, safeParse, refinement.
When & Why to Use This Skill
This Claude skill facilitates Zod-first development by guiding the design and implementation of robust validation schemas. It enables developers to create complex data structures, branded types, and discriminated unions, ensuring seamless TypeScript type inference and runtime data integrity. By automating the creation of schemas, it helps maintain a single source of truth for both type safety and data validation.
Use Cases
- Defining New Data Structures: Creating comprehensive schemas for complex models to serve as the single source of truth for both validation and TypeScript types.
- API Input Validation: Implementing strict runtime validation rules for incoming request data to ensure security and consistency across the application.
- Data Normalization and Transformation: Using Zod transforms to clean, trim, or reformat data automatically during the parsing process to maintain high data quality.
- Domain-Driven Design: Leveraging branded types to enforce type safety across different domain entities, preventing accidental mix-ups of similar primitive types like IDs.
- Handling Polymorphic Data: Designing discriminated unions to safely manage and validate objects that share a common field but have different internal structures.
| name | designing-zod-schemas |
|---|---|
| description | "Designs Zod schemas following Zod-first development. Creates validation schemas, branded types, discriminated unions, and transforms. Infers TypeScript types from schemas. Triggers on: Zod schema, z.object, z.infer, validation, branded types, discriminated union, safeParse, refinement." |
| allowed-tools | "Read, Grep, Glob, Write, Edit" |
Zod Schema Designer
Purpose
Guide the design and implementation of Zod schemas following the project's Zod-first development approach, where schemas are defined before implementing business logic.
When to Use
- Creating new data structures
- Adding validation to inputs
- Designing configuration schemas
- Implementing type-safe transformations
- Creating test data builders
Table of Contents
Core Principles
Zod-First Development
- Define Schema First: Schema is the source of truth
- Infer Types: Use
z.infer<>instead of manual type definitions - Share Validation: Same schema for runtime validation and tests
- Compose Schemas: Build complex schemas from primitives
Decision Guide
| Need | Pattern | Example |
|---|---|---|
| Basic validation | Primitives | z.string().min(1) |
| Domain safety | Branded types | transform((v) => v as EntitySlug) |
| Multiple types | Discriminated union | z.discriminatedUnion('type', [...]) |
| Cross-field rules | Refinement | .refine((data) => ...) |
| Data normalization | Transform | .transform((v) => v.trim()) |
| Partial updates | Partial schema | Schema.partial() |
Quick Reference
Common Schema Shapes
import { z } from 'zod';
// String with constraints
const NameSchema = z.string().min(1).max(100).trim();
// Slug pattern
const SlugSchema = z.string().regex(/^[a-z0-9-]+$/);
// Number with range
const PriceSchema = z.number().min(0).multipleOf(0.01);
// Object schema
const EntitySchema = z.object({
name: z.string().min(1),
slug: z.string().regex(/^[a-z0-9-]+$/),
description: z.string().optional(),
});
// Array with validation
const TagsSchema = z.array(z.string()).min(1).max(10);
// Type inference
type Entity = z.infer<typeof EntitySchema>;
Safe Parsing
const result = schema.safeParse(data);
if (!result.success) {
// Handle errors
console.error(result.error.issues);
} else {
// Use validated data
const validData = result.data;
}
Schema Patterns
For detailed patterns and examples, see:
- Primitive Patterns: Strings, numbers, enums, branded types
- Object Patterns: Objects, discriminated unions, arrays, transforms, refinements
- Testing Patterns: Test data builders, schema validation tests
Project Schema Location
src/modules/config/schema/
├── schema.ts # Main configuration schema
├── primitives.ts # Reusable primitive schemas
├── entities/ # Entity-specific schemas
│ ├── category.ts
│ ├── product.ts
│ └── ...
└── index.ts # Schema exports
Validation Checkpoints
| Phase | Validate | Command |
|---|---|---|
| Schema defined | No TS errors | npx tsc --noEmit |
| Types inferred | z.infer works |
Check type in IDE |
| Validation works | safeParse tests |
pnpm test |
Common Mistakes
| Mistake | Issue | Fix |
|---|---|---|
| Manual type definitions | Type drift | Use z.infer<typeof Schema> |
Using .parse() directly |
Throws on invalid | Use .safeParse() for error handling |
Missing .optional() |
Runtime errors | Mark optional fields explicitly |
| Complex refinements | Hard to debug | Break into smaller schemas |
| Not using branded types | Type confusion | Use .brand() or transform for domain safety |
External Documentation
For up-to-date Zod patterns, use Context7 MCP:
mcp__context7__get-library-docs with context7CompatibleLibraryID: "/colinhacks/zod"
References
{baseDir}/src/modules/config/schema/schema.ts- Main schema definitions{baseDir}/docs/CODE_QUALITY.md#zod-first-development- Quality standards- Zod documentation: https://zod.dev
Related Skills
- Complete entity workflow: See
adding-entity-typesfor full schema-to-service implementation - Testing schemas: See
analyzing-test-coveragefor test data builders - GraphQL type mapping: See
writing-graphql-operationsfor schema-to-GraphQL patterns
Quick Reference Rule
For a condensed quick reference, see .claude/rules/config-schema.md (automatically loaded when editing src/modules/config/**/*.ts files).