zod-skill AGENTS.md

Zod v4 — Complete Guide

This document is for AI agents and LLMs to follow when writing, reviewing, or debugging Zod schemas. It compiles all rules and references into a single executable guide.

Baseline: zod ^4.0.0 with TypeScript ^5.5

---

Abstract

Zod is a TypeScript-first schema validation library for runtime type checking at system boundaries — API input, form data, environment variables, external services. Use z.infer<typeof Schema> for type extraction, safeParse() for validation, and composition methods (.pick(), .omit(), .partial()) to derive schema variants. Zod v4 introduces breaking changes to string formats, enums, error handling, and recursive types. This guide also covers architectural placement (where to parse), schema organization, versioning strategy, and production observability.

---

Table of Contents

1. Parsing & Type Safety — CRITICAL
2. Schema Design — CRITICAL
3. Refinements & Transforms — HIGH
4. Error Handling — HIGH
5. Performance & Composition — MEDIUM
6. v4 Migration — MEDIUM
7. Advanced Patterns — MEDIUM
8. Architecture & Boundaries — CRITICAL/HIGH
9. Observability — HIGH/MEDIUM

---

1. Parsing & Type Safety

Impact: CRITICAL

Rule: Use safeParse() for User Input

parse() throws on invalid input. Use safeParse() which returns a discriminated result.

// INCORRECT — try/catch is verbose and catches unrelated errors
try {
  const user = UserSchema.parse(data)
} catch (e) {
  if (e instanceof z.ZodError) { ... }
}

// CORRECT — discriminated union result
const result = UserSchema.safeParse(data)
if (!result.success) {
  console.log(result.error.issues)
} else {
  console.log(result.data)
}

Use parse() only for internal data that should never be invalid (config, constants).