Zod Schema Designer

Overview

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

1. Define Schema First: Schema is the source of truth
2. Infer Types: Use

   z.infer<>

   instead of manual type definitions
3. Share Validation: Same schema for runtime validation and tests
4. Compose Schemas: Build complex schemas from primitives

Decision Guide

z.string().min(1)

transform((v) => v as EntitySlug)

z.discriminatedUnion('type', [...])

.refine((data) => ...)

.transform((v) => v.trim())

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

• 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

npx tsc --noEmit

z.infer

safeParse

pnpm test

Common Mistakes

z.infer<typeof Schema>

.parse()

.safeParse()

.optional()

.brand()

External Documentation

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

Quick Reference Rule

.claude/rules/config-schema.md

src/modules/config/**/*.ts