Zod Schema Designer
Overview
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
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
Project Schema Conventions
import { z } from 'zod';
// Slug-based entity (Categories, Products, Channels, etc.)
const SlugSchema = z.string().regex(/^[a-z0-9-]+$/);
// Name-based entity (ProductTypes, Attributes, TaxClasses, etc.)
const NameSchema = z.string().min(1).max(100).trim();
// Branded types for domain safety
const EntitySlugSchema = SlugSchema.transform((v) => v as EntitySlug);
// Standard entity shape
const EntitySchema = z.object({
name: z.string().min(1),
slug: z.string().regex(/^[a-z0-9-]+$/),
description: z.string().optional(),
});
// Always infer types from schemas
type Entity = z.infer<typeof EntitySchema>;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 exportsValidation 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).