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 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

Quick Reference Rule

For a condensed quick reference, see .claude/rules/config-schema.md (automatically loaded when editing src/modules/config/**/*.ts files).