Zod v4 - Schema Validation Skill

Zod v4 is a TypeScript-first schema declaration and validation library that provides static type inference, runtime validation, and exceptional performance. Version 4 delivers 14x faster parsing and 66% smaller bundles while maintaining full type safety.

Quick Start

npm install zod@^4.0.0

import * as z from "zod";

// Basic schema creation and validation
const UserSchema = z.object({
  id: z.number().int().positive(),
  email: z.email(),
  username: z.string().min(3).max(20),
  age: z.number().int().min(18).optional(),
});

type User = z.infer<typeof UserSchema>;

// Parse and validate
const user = UserSchema.parse({
  id: 1,
  email: "user@example.com",
  username: "johndoe",
  age: 25,
});

// Safe parsing with error handling
const result = UserSchema.safeParse(input);
if (!result.success) {
  console.log(result.error);
}

Common Patterns

Object Schemas with Validation

// Comprehensive user validation
const UserProfile = z.object({
  id: z.number().int().positive(),
  email: z.email(),
  username: z
    .string()
    .min(3, "Username must be at least 3 characters")
    .max(20, "Username cannot exceed 20 characters")
    .regex(/^[a-zA-Z0-9_]+$/, "Only alphanumeric characters and underscores"),
  age: z.number().int().min(13).max(120),
  role: z.enum(["user", "admin", "moderator"]).default("user"),
  bio: z.string().max(500).optional(),
  website: z.url().optional(),
  createdAt: z.date().default(() => new Date()),
});

// Extending schemas
const AdminProfile = UserProfile.extend({
  permissions: z.array(z.string()),
  accessLevel: z.number().min(1).max(10),
});

String Format Validation

// Built-in format validators
const Validations = {
  email: z.email(),
  uuid: z.uuidv4(),
  url: z.url(),
  ipv4: z.ipv4(),
  ipv6: z.ipv6(),
  base64: z.base64(),
  jwt: z.jwt(),

  // ISO formats
  isoDate: z.iso.date(),
  isoDateTime: z.iso.datetime(),
  isoTime: z.iso.time(),

  // Custom email with specific pattern
  strictEmail: z.email({ pattern: z.regexes.rfc5322Email }),
};

// Template literal validation
const VersionString = z.templateLiteral([
  z.number(),
  ".",
  z.number(),
  ".",
  z.number(),
]);

const CSSValue = z.templateLiteral([
  z.number(),
  z.enum(["px", "em", "rem", "%", "vh", "vw"]),
]);

Array and Collection Validation

// Array with constraints
const NumberArray = z.array(z.number()).min(1).max(100);

// Tuple validation
const Coordinates = z.tuple([z.number(), z.number()]);
const MixedTuple = z.tuple([z.string(), z.number()], z.boolean());

// Set validation
const UniqueStrings = z.set(z.string()).min(3);

// Map validation
const UserPermissions = z.map(
  z.string(), // user ID
  z.array(z.string()), // permissions
);

// Record validation
const StringToNumber = z.record(z.string(), z.number());
const StatusRecord = z.record(
  z.enum(["pending", "active", "complete"]),
  z.boolean(),
);

Union and Discriminated Unions

// Simple union
const StringOrNumber = z.union([z.string(), z.number()]);

// Discriminated union for API responses
const ApiResponse = z.discriminatedUnion("status", [
  z.object({
    status: z.literal("success"),
    data: z.unknown(),
  }),
  z.object({
    status: z.literal("error"),
    error: z.string(),
    code: z.number(),
  }),
  z.object({
    status: z.literal("loading"),
    message: z.string().optional(),
  }),
]);

// Nested discriminated unions
const BaseError = z.object({
  status: z.literal("error"),
  message: z.string(),
});

const DetailedError = z.discriminatedUnion("code", [
  BaseError.extend({ code: z.literal(400), field: z.string() }),
  BaseError.extend({ code: z.literal(401), realm: z.string() }),
  BaseError.extend({ code: z.literal(500), stack: z.string() }),
]);

Custom Refinements and Validation

// Custom validation with refinements
const PasswordSchema = z
  .string()
  .min(8, "Password must be at least 8 characters")
  .refine((val) => /[A-Z]/.test(val), "Must contain uppercase letter")
  .refine((val) => /[a-z]/.test(val), "Must contain lowercase letter")
  .refine((val) => /[0-9]/.test(val), "Must contain number")
  .refine((val) => /[^A-Za-z0-9]/.test(val), "Must contain special character");

// Complex validation with superRefine
const UserRegistration = z
  .object({
    email: z.email(),
    password: z.string(),
    confirmPassword: z.string(),
    age: z.number(),
    termsAccepted: z.boolean(),
  })
  .superRefine((data, ctx) => {
    if (data.password !== data.confirmPassword) {
      ctx.addIssue({
        code: "custom",
        path: ["confirmPassword"],
        message: "Passwords must match",
      });
    }

    if (data.age < 18 && !data.termsAccepted) {
      ctx.addIssue({
        code: "custom",
        path: ["termsAccepted"],
        message: "Parental consent required for users under 18",
      });
    }
  });

Transformations and Data Processing

// Transform data during validation
const StringToNumber = z
  .string()
  .transform((val) => parseInt(val, 10))
  .refine((val) => !isNaN(val), "Must be a valid number");

const TimestampToDate = z
  .number()
  .transform((timestamp) => new Date(timestamp));

const NormalizeEmail = z.string().transform((val) => val.toLowerCase().trim());

// Overwrite for type-preserving transforms
const RoundNumber = z.number().overwrite((val) => Math.round(val));

// Pipeline transformations
const ProcessUrl = z
  .string()
  .transform((val) => val.trim())
  .transform((val) => val.toLowerCase())
  .transform((val) => {
    try {
      return new URL(val);
    } catch {
      throw new Error("Invalid URL format");
    }
  });

Recursive Schemas

// Recursive category structure
const Category = z.object({
  id: z.number(),
  name: z.string(),
  get subcategories() {
    return z.array(Category);
  },
});

// Mutually recursive types
const User = z.object({
  id: z.number(),
  name: z.string(),
  get posts() {
    return z.array(Post);
  },
});

const Post = z.object({
  id: z.number(),
  title: z.string(),
  content: z.string(),
  get author() {
    return User;
  },
  get comments() {
    return z.array(Comment);
  },
});

const Comment = z.object({
  id: z.number(),
  text: z.string(),
  get author() {
    return User.pick({ id: true, name: true });
  },
});

File Validation

// File upload validation
const ImageUpload = z.object({
  avatar: z
    .file()
    .max(5_000_000, "File must be less than 5MB")
    .mime(["image/jpeg", "image/png", "image/webp"], "Must be an image"),

  banner: z
    .file()
    .max(10_000_000, "File must be less than 10MB")
    .mime(["image/jpeg", "image/png"], "Must be JPEG or PNG")
    .optional(),
});

// Document validation
const DocumentUpload = z
  .file()
  .min(1000, "File must be at least 1KB")
  .max(50_000_000, "File must be less than 50MB")
  .mime([
    "application/pdf",
    "application/msword",
    "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
  ]);

Function Validation

// Define validated functions
const CalculateTax = z.function({
  input: [z.number().min(0), z.number().min(0).max(1)],
  output: z.number(),
});

const taxCalculator = CalculateTax.implement((amount, rate) => {
  return amount * rate;
});

// Async function validation
const FetchUser = z.function({
  input: [z.number().int().positive()],
  output: z.object({
    id: z.number(),
    name: z.string(),
    email: z.email(),
  }),
});

const getUser = FetchUser.implementAsync(async (id) => {
  const response = await fetch(`/api/users/${id}`);
  return response.json();
});

Error Handling

// Custom error messages
const CustomValidation = z.object({
  username: z
    .string({
      error: (issue) => {
        if (issue.input === undefined) return "Username is required";
        if (typeof issue.input !== "string") return "Username must be a string";
        return "Invalid username";
      },
    })
    .min(3, "Username must be at least 3 characters"),
});

// Error handling patterns
const validateInput = (input: unknown) => {
  const result = UserSchema.safeParse(input);

  if (!result.success) {
    const error = result.error;

    // Pretty print errors
    console.log(z.prettifyError(error));

    // Extract field errors
    const fieldErrors = error.issues.reduce(
      (acc, issue) => {
        const field = issue.path.join(".");
        acc[field] = issue.message;
        return acc;
      },
      {} as Record<string, string>,
    );

    return { success: false, errors: fieldErrors };
  }

  return { success: true, data: result.data };
};

Default Values and Coercion

// Schema with defaults
const ConfigSchema = z.object({
  theme: z.enum(["light", "dark"]).default("light"),
  notifications: z.boolean().default(true),
  fontSize: z.number().min(10).max(30).default(14),
  timeout: z.number().default(5000),
});

// Type coercion
const CoercedConfig = z.object({
  port: z.coerce.number().default(3000),
  https: z.coerce.boolean().default(false),
  maxConnections: z.coerce.number().int().positive().default(100),
});

// Environment variable parsing
const EnvSchema = z.object({
  NODE_ENV: z
    .enum(["development", "production", "test"])
    .default("development"),
  PORT: z.coerce.number().default(3000),
  DEBUG: z.stringbool().default("false"),
});

Zod Mini (Tree-Shakable)

import * as z from "zod/mini";

// Functional API for smaller bundles
const OptionalString = z.optional(z.string());
const StringArray = z.array(z.string());
const StringOrNumber = z.union([z.string(), z.number()]);

// Check functions for validations
const ValidatedEmail = z
  .string()
  .check(z.regex(/@/), z.minLength(5), z.maxLength(100));

const PositiveInt = z.number().check(z.int(), z.positive(), z.lt(1000));

const NonEmptyArray = z.array(z.any()).check(z.minSize(1));

Practical Examples

Form Validation

// Contact form validation
const ContactForm = z.object({
  name: z.string().min(1, "Name is required").max(100),
  email: z.email("Please provide a valid email"),
  subject: z.string().min(5, "Subject must be at least 5 characters"),
  message: z.string().min(10, "Message must be at least 10 characters"),
  newsletter: z.boolean().default(false),
});

// React form integration
const handleSubmit = (formData: FormData) => {
  const data = {
    name: formData.get("name"),
    email: formData.get("email"),
    subject: formData.get("subject"),
    message: formData.get("message"),
    newsletter: formData.get("newsletter") === "on",
  };

  const result = ContactForm.safeParse(data);
  if (!result.success) {
    const errors = result.error.flatten();
    return { errors: errors.fieldErrors };
  }

  // Process valid data
  return { success: true, data: result.data };
};

API Response Validation

// API response schemas
const UserResponse = z.object({
  data: z.object({
    id: z.number(),
    name: z.string(),
    email: z.email(),
    createdAt: z.string().transform((val) => new Date(val)),
  }),
  meta: z.object({
    total: z.number(),
    page: z.number(),
    totalPages: z.number(),
  }),
});

// Typed API client
const apiClient = {
  async getUser(id: number): Promise<z.infer<typeof UserResponse>["data"]> {
    const response = await fetch(`/api/users/${id}`);
    const data = await response.json();

    const result = UserResponse.safeParse(data);
    if (!result.success) {
      throw new Error(`Invalid API response: ${result.error.message}`);
    }

    return result.data.data;
  },
};

Configuration Validation

// Application configuration
const AppConfig = z.object({
  server: z.object({
    port: z.coerce.number().min(1).max(65535).default(3000),
    host: z.string().default("localhost"),
    cors: z.boolean().default(true),
  }),
  database: z.object({
    url: z.string(),
    ssl: z.boolean().default(false),
    maxConnections: z.coerce.number().int().positive().default(10),
  }),
  auth: z.object({
    jwtSecret: z.string().min(32),
    tokenExpiry: z.string().default("24h"),
    refreshExpiry: z.string().default("7d"),
  }),
});

// Load and validate config
const loadConfig = (configPath: string) => {
  const rawConfig = require(configPath);
  const config = AppConfig.parse(rawConfig);
  return config;
};

Requirements

• TypeScript: 4.5+ (recommended for best inference)
• Runtime: Node.js, browsers, Deno, Bun
• Bundle size: 5.36kb gzipped (full), 1.88kb gzipped (mini)

Installation

# Full Zod v4
npm install zod@^4.0.0

# For minimal bundle size
npm install zod@^4.0.0
# Then import from "zod/mini"

Key Features

• Static Type Inference: Automatic TypeScript type generation from schemas
• Runtime Validation: Comprehensive input validation with detailed errors
• Performance: 14x faster parsing than v3, optimized for production
• Tree Shakable: Zod Mini provides 85% bundle size reduction
• Template Literals: Validate string patterns matching TypeScript template literals
• File Validation: Built-in File object validation with size and MIME type constraints
• Recursive Types: Full support for recursive and self-referential schemas
• JSON Schema: First-party JSON Schema generation
• Function Validation: Type-safe function definitions with validated inputs/outputs