Zod (Schema Validation)

Overview

Zod is a TypeScript-first schema declaration and validation library. Define a schema once, get both runtime validation AND TypeScript types automatically via z.infer<>.

Version: Zod 4 (2025) / Zod 3.x widely used
Requirements: TypeScript ≥5.5, strict mode

Key Benefit: Single source of truth for validation and types — no drift between runtime checks and TypeScript.

When to Use This Skill

✅ Use Zod when:

• Validating API inputs (required for tRPC)
• Building forms with react-hook-form
• Parsing environment variables
• Validating config files or JSON
• Creating DTOs between layers
• Any data crossing trust boundaries

❌ Zod is NOT for:

• Complex business rule validation (use domain logic)
• Database schema definition (use Prisma schema)
• Static type-only definitions (use interfaces)

Quick Start

Installation

npm install zod

Basic Usage

import { z } from 'zod';

// Define schema
const UserSchema = z.object({
  id: z.string().uuid(),
  email: z.string().email(),
  age: z.number().int().positive().optional(),
});

// Infer TypeScript type
type User = z.infer<typeof UserSchema>;

// Validate
const result = UserSchema.safeParse(data);
if (result.success) {
  console.log(result.data); // typed as User
} else {
  console.log(result.error.issues);
}

Core Schema Patterns

Primitives with Validation

const EmailSchema = z.string().email('Invalid email format');
const PasswordSchema = z.string().min(8, 'Min 8 characters');
const AgeSchema = z.number().int().positive().max(150);
const UrlSchema = z.string().url();
const UuidSchema = z.string().uuid();

Object Schemas

const UserSchema = z.object({
  id: z.string().uuid(),
  email: z.string().email(),
  name: z.string().min(2).max(100),
  role: z.enum(['user', 'admin', 'moderator']),
  createdAt: z.date(),
});

type User = z.infer<typeof UserSchema>;

Derive Variations

// For create (omit auto-generated fields)
const CreateUserSchema = UserSchema.omit({ id: true, createdAt: true });

// For update (all optional)
const UpdateUserSchema = CreateUserSchema.partial();

// For public response (only safe fields)
const PublicUserSchema = UserSchema.pick({ id: true, name: true });

Advanced Patterns

Discriminated Unions

Use for type-safe API responses:

const ApiResponse = z.discriminatedUnion('status', [
  z.object({ status: z.literal('success'), data: UserSchema }),
  z.object({ status: z.literal('error'), code: z.string(), message: z.string() }),
]);

type ApiResponse = z.infer<typeof ApiResponse>;
// TypeScript knows: if status === 'success', data exists

Custom Validation with Refine

const PasswordSchema = z.string()
  .min(8)
  .refine(val => /[A-Z]/.test(val), 'Must contain uppercase')
  .refine(val => /[0-9]/.test(val), 'Must contain number');

Cross-Field Validation with SuperRefine

const FormSchema = z.object({
  password: z.string(),
  confirmPassword: z.string(),
}).superRefine((data, ctx) => {
  if (data.password !== data.confirmPassword) {
    ctx.addIssue({
      code: 'custom',
      message: 'Passwords must match',
      path: ['confirmPassword'],
    });
  }
});

Transforms (Data Normalization)

// Normalize email
const NormalizedEmail = z.string()
  .email()
  .transform(s => s.toLowerCase().trim());

// Parse string to number
const StringToNumber = z.string()
  .transform(s => parseInt(s, 10))
  .pipe(z.number());

Coercion (API Query Parameters)

// GET requests receive strings — use coercion
const PaginationSchema = z.object({
  page: z.coerce.number().int().min(1).default(1),
  limit: z.coerce.number().int().min(1).max(100).default(20),
  active: z.coerce.boolean().optional(),
});

Common Schema Recipes

Pagination Input

export const PaginationSchema = z.object({
  limit: z.number().min(1).max(100).default(10),
  cursor: z.string().uuid().optional(),
});

Date Range Filter

export const DateRangeSchema = z.object({
  from: z.coerce.date(),
  to: z.coerce.date(),
}).refine(d => d.from <= d.to, 'From must be before To');

Environment Variables

const EnvSchema = z.object({
  NODE_ENV: z.enum(['development', 'production', 'test']),
  DATABASE_URL: z.string().url(),
  JWT_SECRET: z.string().min(32),
  PORT: z.coerce.number().default(3000),
});

export const env = EnvSchema.parse(process.env);

File Upload Metadata

const FileSchema = z.object({
  name: z.string(),
  size: z.number().max(10 * 1024 * 1024), // 10MB
  type: z.enum(['image/png', 'image/jpeg', 'application/pdf']),
});

Integration with tRPC

import { z } from 'zod';
import { publicProcedure } from '../trpc';

const CreateUserSchema = z.object({
  email: z.string().email(),
  name: z.string().min(2),
});

export const userRouter = router({
  create: publicProcedure
    .input(CreateUserSchema)  // ← Zod validates automatically
    .mutation(({ input }) => {
      // input is typed as { email: string; name: string }
    }),
});

Rules

Do ✅

• Use z.infer<typeof Schema> to derive types
• Use discriminated unions over regular unions for objects
• Use .safeParse() when handling errors gracefully
• Add descriptive error messages
• Use .default() for optional fields with defaults
• Keep schemas in dedicated files (/schemas/*.schema.ts)

Avoid ❌

• Async transforms in tRPC input (not supported)
• Using .catchall() with output schemas (inference issues)
• Multiple Zod installations (causes type inference failures)
• Overly complex nested refinements (hard to debug)

Parse Methods

Use .safeParse() in application code, .parse() in trusted contexts.

Troubleshooting

"Type inference not working":
  → Check single Zod installation: npm ls zod
  → Ensure TypeScript strict mode enabled
  → Restart TypeScript server

"Coercion not working":
  → Use z.coerce.number() not z.number() for query params
  → Check input is string before coercion

"Transform output type wrong":
  → Use .pipe() after transform for additional validation
  → Check transform return type

"Refinement errors unclear":
  → Add path parameter to ctx.addIssue()
  → Use descriptive error messages

File Structure

src/schemas/
├── user.schema.ts       # User-related schemas
├── post.schema.ts       # Post-related schemas
├── common.schema.ts     # Pagination, date ranges, etc.
└── env.schema.ts        # Environment validation

References

• https://zod.dev — Official documentation
• https://zod.dev/?id=basic-usage — Quick reference
• https://github.com/colinhacks/zod — GitHub