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

Core Principles
Quick Reference
Schema Patterns
Project Schema Location
References

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-types for full schema-to-service implementation
Testing schemas: See analyzing-test-coverage for test data builders
GraphQL type mapping: See writing-graphql-operations for schema-to-GraphQL patterns

designing-zod-schemas

Install Skill

SKILL.md