designing-zod-schemas

saleor's avatarfrom saleor

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.

⭐20stars🔀2forks📁View on GitHub🕐Updated Dec 15, 2025⬇️2downloads

When & Why to Use This Skill

This Claude skill facilitates Zod-first development by guiding the design and implementation of robust validation schemas. It enables developers to create complex data structures, branded types, and discriminated unions, ensuring seamless TypeScript type inference and runtime data integrity. By automating the creation of schemas, it helps maintain a single source of truth for both type safety and data validation.

Use Cases

  • Defining New Data Structures: Creating comprehensive schemas for complex models to serve as the single source of truth for both validation and TypeScript types.
  • API Input Validation: Implementing strict runtime validation rules for incoming request data to ensure security and consistency across the application.
  • Data Normalization and Transformation: Using Zod transforms to clean, trim, or reformat data automatically during the parsing process to maintain high data quality.
  • Domain-Driven Design: Leveraging branded types to enforce type safety across different domain entities, preventing accidental mix-ups of similar primitive types like IDs.
  • Handling Polymorphic Data: Designing discriminated unions to safely manage and validate objects that share a common field but have different internal structures.
namedesigning-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

Table of Contents

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

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:

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
  • 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).