Skip to content
AyoKoding

Overview

Want to master Zod schema validation through code? This by-example tutorial provides 80 heavily annotated examples covering 95% of Zod's API. Learn runtime validation, type inference, transforms, refinements, and production integration patterns through working code rather than lengthy explanations.

What Is By-Example Learning?

By-example learning is a code-first approach where you learn concepts through annotated, working examples rather than narrative explanations. Each example shows:

  1. What the code does - Brief explanation of the Zod concept
  2. How it works - A focused, heavily commented code example
  3. Key Takeaway - A pattern summary highlighting the key takeaway
  4. Why It Matters - Production context, when to use, deeper significance

This approach works best when you already understand TypeScript fundamentals and have experience building applications. You learn Zod's schema model, validation patterns, and type inference by studying real code rather than theoretical descriptions.

What Is Zod?

Zod is a TypeScript-first schema declaration and validation library that bridges the gap between TypeScript's compile-time type safety and runtime data validation. Key distinctions:

  • TypeScript-first: Schemas automatically infer TypeScript types — no duplicate type definitions
  • Runtime validation: Validates data that TypeScript cannot see at compile time (API responses, user input, environment variables)
  • Zero dependencies: Ships with no external dependencies; minimal bundle impact
  • Composable: Schemas compose into complex validators through chaining, merging, and nesting
  • Ecosystem integration: First-class support for tRPC, React Hook Form, Next.js, and most TypeScript frameworks

Learning Path

graph TD
  A["Beginner<br/>Zod Fundamentals<br/>Examples 1-28"] --> B["Intermediate<br/>Production Patterns<br/>Examples 29-55"]
  B --> C["Advanced<br/>Expert Mastery<br/>Examples 56-80"]
  D["0%<br/>No Zod Knowledge"] -.-> A
  C -.-> E["95%<br/>Zod Mastery"]
 
  style A fill:#0173B2,color:#fff
  style B fill:#DE8F05,color:#fff
  style C fill:#029E73,color:#fff
  style D fill:#CC78BC,color:#fff
  style E fill:#029E73,color:#fff

Coverage Philosophy: 95% Through 80 Examples

The 95% coverage means you'll understand Zod deeply enough to validate any production data with confidence. It doesn't mean you'll know every edge case or internal API — those come with experience.

The 80 examples are organized progressively:

  • Beginner (Examples 1-28): Foundation schemas (primitives, objects, arrays, enums, unions, optionals, nullables, defaults, tuples, records, maps, sets, dates, type inference, parse vs safeParse)
  • Intermediate (Examples 29-55): Production patterns (refinements, transforms, preprocessors, pipes, discriminated unions, recursive schemas, lazy schemas, custom errors, schema composition, form validation, API validation, coercion)
  • Advanced (Examples 56-80): Expert mastery (branded types, custom ZodType, OpenAPI integration, tRPC integration, React Hook Form integration, performance optimization, conditional schemas, generic schemas, custom error maps, z.function(), effect schemas, migration patterns)

Together, these examples cover 95% of what you'll use in production TypeScript applications.

Annotation Density: 1-2.25 Comments Per Code Line

CRITICAL: All examples maintain 1-2.25 comment lines per code line PER EXAMPLE to ensure deep understanding.

What this means:

  • Simple lines get 1 annotation explaining purpose or result
  • Complex lines get 2+ annotations explaining behavior, types, and side effects
  • Use // => notation to show expected values, outputs, or inferred types

Example:

import { z } from "zod";
 
const UserSchema = z.object({
  // => Creates ZodObject schema
  name: z.string(), // => name field: string, required
  age: z.number().min(0), // => age field: number, must be >= 0
  // => min(0) adds runtime constraint
});
 
type User = z.infer<typeof UserSchema>; // => Extracts TypeScript type from schema
// => User = { name: string; age: number }
 
const result = UserSchema.safeParse({ name: "Aisha", age: 28 });
// => safeParse: returns { success: true, data: ... } or { success: false, error: ... }
// => Does NOT throw — safe for handling invalid data
 
if (result.success) {
  console.log(result.data.name); // => Output: "Aisha"
  // => TypeScript narrows result.data to User
}

This density ensures each example is self-contained and fully comprehensible without external documentation.

Structure of Each Example

All examples follow a consistent five-part format:

### Example N: Descriptive Title

2-3 sentence explanation of the concept.

```typescript
// Heavily annotated code example
// showing the Zod pattern in action

Key Takeaway: 1-2 sentence summary.

Why It Matters: 50-100 words explaining significance in production applications.


**Code annotations**:

- `// =>` shows inferred types, expected output, validation results
- Inline comments explain what each schema method does
- Variable names are self-documenting
- Type annotations make data flow explicit

## What's Covered

### Primitive Schemas

- **Strings**: `z.string()`, string methods (min, max, email, url, uuid, regex)
- **Numbers**: `z.number()`, number methods (min, max, int, positive, negative)
- **Booleans**: `z.boolean()`, boolean coercion
- **Dates**: `z.date()`, date range validation
- **Literals**: `z.literal()`, exact value matching
- **Enums**: `z.enum()`, `z.nativeEnum()`, enum access

### Composite Schemas

- **Objects**: `z.object()`, strict/strip/passthrough modes
- **Arrays**: `z.array()`, length constraints, non-empty arrays
- **Tuples**: `z.tuple()`, fixed-length typed arrays
- **Records**: `z.record()`, typed key-value pairs
- **Maps**: `z.map()`, typed Map structures
- **Sets**: `z.set()`, typed Set structures

### Schema Modifiers

- **Optional/Nullable**: `.optional()`, `.nullable()`, `.nullish()`
- **Defaults**: `.default()`, `.catch()`
- **Union Types**: `z.union()`, discriminated unions
- **Intersections**: `z.intersection()`, schema merging

### Validation and Parsing

- **Parse Methods**: `.parse()`, `.safeParse()`, `.parseAsync()`, `.safeParseAsync()`
- **Type Inference**: `z.infer<>`, `z.input<>`, `z.output<>`
- **Error Handling**: `ZodError`, error formatting, custom error messages
- **Refinements**: `.refine()`, `.superRefine()`, cross-field validation

### Transforms and Preprocessing

- **Transforms**: `.transform()`, data reshaping and mapping
- **Preprocessing**: `z.preprocess()`, input coercion
- **Pipes**: `.pipe()`, schema chaining
- **Coercion**: `z.coerce.*`, automatic type conversion

### Schema Composition

- **Object Methods**: `.merge()`, `.extend()`, `.pick()`, `.omit()`, `.partial()`, `.required()`
- **Recursive Schemas**: `z.lazy()`, recursive data structures
- **Schema Utilities**: `.and()`, `.or()`, `.brand()`, `.readonly()`

### Production Integration

- **Form Validation**: React Hook Form + Zod integration
- **API Validation**: Request/response schema validation
- **tRPC Integration**: Schema-first API definition
- **OpenAPI**: Schema to OpenAPI spec generation

### Advanced Patterns

- **Branded Types**: Type-safe nominal typing
- **Custom ZodType**: Extending Zod with custom validators
- **Generic Schemas**: Reusable parameterized schemas
- **z.function()**: Function schema validation
- **Custom Error Maps**: Global error customization
- **Effect Schemas**: `.transform()` with effects pattern

## What's NOT Covered

We exclude topics that belong in specialized tutorials:

- **Zod Internals**: Parser implementation details, AST traversal
- **Alternative Libraries**: Yup, io-ts, Valibot comparisons (brief migration examples only)
- **Build Configuration**: TypeScript strict mode setup (assumed)
- **Framework Internals**: Next.js, tRPC source code
- **Advanced TypeScript**: Conditional types, mapped types unrelated to Zod

For these topics, see dedicated tutorials and the official Zod documentation.

## Prerequisites

### Required

- **TypeScript fundamentals**: Types, interfaces, generics, type inference
- **ES6+ JavaScript**: Destructuring, spread operators, async/await
- **npm/module system**: Package installation and imports
- **Programming experience**: You've built TypeScript applications before

### Recommended

- **React basics**: Helpful for form validation examples
- **REST API concepts**: Helpful for API validation examples
- **tRPC awareness**: Helpful for advanced integration examples

### Not Required

- **Zod experience**: This guide assumes you're new to Zod
- **Advanced TypeScript**: We explain TypeScript patterns as needed
- **Functional programming**: Helpful but not required

## Getting Started

Before starting the examples, ensure Zod is installed:

```bash
npm install zod

All examples use import { z } from "zod" and are runnable in a TypeScript environment (Node.js with tsx or ts-node, or browser with bundler).

# Run examples directly with tsx
npx tsx example.ts

How to Use This Guide

1. Choose Your Starting Point

  • New to Zod? Start with Beginner (Example 1)
  • Know basic schemas? Start with Intermediate (Example 29)
  • Building production integration? Jump to Advanced (Example 56)

2. Read the Example

Each example has five parts:

  • Explanation (2-3 sentences): What Zod concept, why it exists, when to use it
  • Code (heavily commented): Working TypeScript code showing the pattern
  • Key Takeaway (1-2 sentences): Distilled essence of the pattern
  • Why It Matters (50-100 words): Production context and deeper significance

3. Run the Code

Create a test file and run each example:

mkdir zod-examples && cd zod-examples
npm init -y
npm install zod tsx typescript
# Paste example code into example.ts
npx tsx example.ts

4. Modify and Experiment

Change schemas, add invalid data, break validations on purpose. Experimentation builds intuition faster than reading.

5. Reference as Needed

Use this guide as a reference when building features. Search for relevant examples and adapt patterns to your code.

Ready to Start?

Choose your learning path:

  • Beginner - Start here if new to Zod. Build foundation understanding through 28 core examples.
  • Intermediate - Jump here if you know basic schemas. Master production patterns through 27 examples.
  • Advanced - Expert mastery through 25 advanced examples covering integrations, branded types, and optimization.

Or jump to specific topics by searching for relevant example keywords (parse, refine, transform, form, API, branded, tRPC, etc.).

Examples by Level

Beginner (Examples 1–28)

Intermediate (Examples 29–55)

Advanced (Examples 56–80)

Last updated March 24, 2026

Command Palette

Search for a command to run...