/zod

name: zod
description: TypeScript-first schema validation and type inference. Use for validating API requests/responses, form data, env vars, configs, defining type-safe schemas with runtime validation, transforming data, generating JSON Schema for OpenAPI/AI, or encountering missing validation errors, type inference issues, validation error handling problems. Zero dependencies, compact core (~5kb gzipped; zod/mini ~1.9kb).
license: MIT
metadata:
  version: 2.1.0
  last_verified: 2026-08-20
  package_version: 4.4.x
  keywords:
    - zod
    - validation
    - schema
    - typescript
    - type-safety
    - runtime-validation
    - type-inference
    - data-validation
    - form-validation
    - api-validation
    - json-schema
    - refinement
    - transformation
    - error-handling
    - parse
    - safeParse
    - z.object
    - z.string
    - z.number
    - z.array
    - z.union
    - z.discriminatedUnion
    - z.refine
    - z.transform
    - z.infer
    - z.coerce
    - z.enum
    - z.literal
    - z.tuple
    - z.record
    - z.intersection
    - z.codec
    - z.toJSONSchema
    - z.treeifyError
    - z.flattenError
    - z.prettifyError
    - z.registry
    - z.globalRegistry
    - .register
    - .meta
    - error-customization
    - localization
    - i18n
    - migration
    - v3-to-v4
    - breaking-changes
    - tRPC
    - prisma-zod
    - react-hook-form
    - trpc
    - environment-variables
    - env-validation
    - config-validation
    - dto
    - type-guard
    - runtime-type-checking
    - zod-mini
    - z.core
    - z.preprocess
    - z.custom
    - z.templateLiteral
    - z.catchall
    - z.check
    - z.file
    - z.json
    - z.stringbool
    - z.xor
    - z.exactOptional
    - z.safeExtend
    - z.fromJSONSchema
    - best-practices
    - performance
  token_savings: 65%
  errors_prevented: 8
  production_tested: true
  related_skills:
    - react-hook-form-zod

Zod: TypeScript-First Schema Validation

Overview

Zod is a TypeScript-first validation library that enables developers to define schemas for validating data at runtime while automatically inferring static TypeScript types. With zero dependencies and a compact core (~5kb gzipped; ~1.9kb for `zod/mini`), Zod provides immutable, composable validation with comprehensive error handling.

Installation

bun add zod
# or
npm install zod
# or
pnpm add zod
# or
yarn add zod

**Requirements**:

• TypeScript v5.5+ with `"strict": true` in `tsconfig.json`
• Zod 4.x (4.4.x recommended; `z.codec()` requires 4.1+)

**Important**: This skill documents **Zod 4.x** features. The following APIs require Zod 4 and are NOT available in Zod 3.x:

• `z.codec()` - Bidirectional transformations
• `z.iso.date()`, `z.iso.time()`, `z.iso.datetime()`, `z.iso.duration()` - ISO format validators
• `z.toJSONSchema()` - JSON Schema generation
• `z.treeifyError()`, `z.prettifyError()`, `z.flattenError()` - New error formatting helpers
• `.meta()` - Enhanced metadata (Zod 3.x only has `.describe()`)
• Unified `error` parameter - Replaces `message`, `invalid_type_error`, `required_error`, `errorMap`
• `.check()` - Low-level multi-issue validation (composes check factories like `z.minLength(3)`)
• `z.file()`, `z.json()`, `z.stringbool()`, `z.xor()`, `z.templateLiteral()` - New schema types
• `z.exactOptional()`, `.prefault()`, `.safeExtend()`, `z.fromJSONSchema()` - New utilities

For Zod 3.x compatibility or migration guidance, see https://zod.dev

**Import paths** (all ship in the `zod` package):

• `import { z } from "zod"` — standard (v4 since 4.0)
• `import { z } from "zod/v4"` — pin for libraries supporting both v3 (3.25+) and v4 users
• `import { z } from "zod/mini"` — functional, tree-shakable API (~1.9kb; checks via `.check(z.minLength(3))`)
• `import * as core from "zod/v4/core"` — low-level `$`-prefixed internals for library authors

Migrating from Zod v3 to v4

**Load `references/migration-guide.md` for complete v3 to v4 migration documentation.**

Quick Summary

Zod v4 introduces breaking changes for better performance:

• **Error customization**: Use unified `error` parameter (replaces `message`, `invalid_type_error`, `required_error`)
• **Number validation**: Stricter - rejects `Infinity` and unsafe integers
• **String formats**: Prefer top-level functions (`z.email()` instead of `z.string().email()`; the method forms still work but are deprecated)
• **Object defaults**: Applied even in optional fields
• **Deprecated APIs**: Use `.extend()` (not `.merge()`), `z.treeifyError()` (not `error.format()`)
• **Function validation**: Use `.implement()` method
• **UUID validation**: Stricter RFC 9562/4122 compliance

**→ Load `references/migration-guide.md` for:** Complete breaking changes, migration checklist, gradual migration strategy, rollback instructions

Core Concepts

Basic Usage Pattern

import { z } from "zod";

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

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

// Validate data (throws on error)
const user = UserSchema.parse(data);

// Validate data (returns result object)
const result = UserSchema.safeParse(data);
if (result.success) {
  console.log(result.data); // Typed!
} else {
  console.error(result.error); // ZodError
}

Parsing Methods

Use the appropriate parsing method based on error handling needs:

• **`.parse(data)`** - Throws `ZodError` on invalid input; returns strongly-typed data on success
• **`.safeParse(data)`** - Returns `{ success: true, data }` or `{ success: false, error }` (no exceptions)
• **`.parseAsync(data)`** - For schemas with async refinements/transforms
• **`.safeParseAsync(data)`** - Async version that doesn't throw

**Best Practice**: Use `.safeParse()` to avoid try-catch blocks and leverage discriminated unions.

Primitive Types

Strings

z.string()