SKILL.md
Zod Schema Validation
You are an expert in Zod schema validation and type inference for TypeScript applications.
Core Principles
- Utilize Zod for schema validation and type inference
- Validate data at system boundaries (API, forms, external data)
- Leverage TypeScript type inference from Zod schemas
- Implement early returns and guard clauses for validation errors
Schema Design
Basic Schema
import { z } from 'zod'const UserSchema = z.object({
id: z.string().uuid(),
email: z.string().email(),
name: z.string().min(1).max(100),
age: z.number().int().positive().optional(),
role: z.enum(['admin', 'user', 'guest']),
createdAt: z.date(),
})
type User = z.infer
### Best Practices
- Define schemas close to where they're used
- Use `.infer` to derive TypeScript types
- Compose schemas using `.extend()`, `.merge()`, `.pick()`, `.omit()`
- Create reusable base schemas for common patterns
## Validation Patterns
### Safe Parsing
const result = UserSchema.safeParse(data)
if (!result.success) {
console.error(result.error.format())
return
}
// result.data is typed as User
### Transform and Refine
const schema = z.string()
.transform((val) => val.trim().toLowerCase())
.refine((val) => val.length > 0, 'Cannot be empty')
## Form Integration
- Use Zod with react-hook-form via `@hookform/resolvers/zod`
- Define form schemas that match your form structure
- Handle validation errors in UI appropriately
- Use `.partial()` for optional update forms
## API Validation
- Validate request bodies in API routes
- Validate query parameters and path params
- Return structured error responses
- Use discriminated unions for different response types
## Error Handling
- Implement custom error messages for better UX
- Use `.format()` for structured error output
- Create custom error maps for i18n support
- Handle nested object errors appropriately
## Advanced Patterns
### Discriminated Unions
const ResultSchema = z.discriminatedUnion('status', [
z.object({ status: z.literal('success'), data: UserSchema }),
z.object({ status: z.literal('error'), message: z.string() }),
])
### Recursive Schemas
const CategorySchema: z.ZodType<Category> = z.lazy(() =>
z.object({
name: z.string(),
children: z.array(CategorySchema),
})
)