Zod

Zod

Overview

Zod is a TypeScript-first schema validation library with static type inference. Define a schema once; you get both runtime validation and a TypeScript type (via z.infer). Zero external dependencies; works in Node and browsers. Ideal for forms (e.g. with react-hook-form), API parsing, env vars, and any untrusted input.

Requirements: TypeScript 5.5+ recommended; enable `strict` in tsconfig.json.

Install: Add zod via your package manager. See zod.dev.

---

Quick start

import { z } from "zod";

const User = z.object({
  name: z.string(),
  age: z.number().optional(),
});

type User = z.infer<typeof User>;
// { name: string; age?: number }

const data = User.parse(input); // throws ZodError if invalid
const result = User.safeParse(input); // { success: true, data } | { success: false, error }

---

Primitives and common types

Optional: .optional() → T | undefined. Nullable: .nullable() → T | null. Nullish: .nullish() → T | null | undefined. Default: .default(value).

---

Objects

const Schema = z.object({
  name: z.string(),
  age: z.number().optional(),
  tags: z.array(z.string()).default([]),
});

type Schema = z.infer<typeof Schema>;

• .shape: Schema.shape.name (access field schema).
• .keyof(): Schema.keyof() → enum of keys.
• .extend({ ... }): Add or override keys.
• .pick({ name }) / .omit({ age }): Subset of keys.
• .partial() / .required({ name }): Optionalize or require.
• .strict(): No extra keys (default in z.object). z.strictObject / z.looseObject for behavior variants.
• .catchall(z.string()): Allow extra keys with a schema.
• Nested: z.object({ user: z.object({ name: z.string() }) }).
• Recursive: z.lazy(() => Category) for self-referential structures.

---

Arrays and tuples

• Arrays: z.array(z.string()), z.string().array().
• Tuples: z.tuple([z.string(), z.number()]) — fixed length and types.
• Non-empty: .min(1) or dedicated helpers if available.

---

Unions and intersections

• Union: z.union([z.string(), z.number()]) or z.string().or(z.number()).
• Discriminated union: Use a common key (e.g. type: "a") and z.discriminatedUnion("type", [z.object({ type: z.literal("a"), ... }), ...]).
• Intersection: z.intersection(A, B) or A.and(B).

---

Refinements and transform

• .refine(fn, message?): Custom validation; keep type unchanged.
• .superRefine: Multiple issues or async; push to ctx.
• .transform(fn): Change output type. Input and output can differ; use z.input<typeof schema> and z.output<typeof schema> (or z.infer for output).
• .pipe(otherSchema): Chain validation/transform (e.g. string → number via z.string().pipe(z.coerce.number())).

---

Parsing and errors

• .parse(input): Returns data or throws ZodError.
• .safeParse(input): Returns { success: true, data } or { success: false, error: ZodError }.
• ZodError: error.issues (array of { path, message, code }), error.format() for nested shape.
• Async: .parseAsync / .safeParseAsync for schemas with async refinements or transforms.

---

Type inference

• z.infer<typeof schema>: Output type (after transforms/defaults).
• z.input<typeof schema>: Input type (before transforms; useful when input ≠ output).
• z.output<typeof schema>: Same as z.infer for output type.

const S = z.string().transform((s) => s.length);
type In = z.input<typeof S>;  // string
type Out = z.output<typeof S>; // number

---

Integration: React Hook Form

Use @hookform/resolvers with zodResolver:

import { zodResolver } from "@hookform/resolvers/zod";
import { useForm } from "react-hook-form";
import { z } from "zod";

const formSchema = z.object({
  email: z.string().email(),
  password: z.string().min(8),
});

type FormValues = z.infer<typeof formSchema>;

const form = useForm<FormValues>({
  resolver: zodResolver(formSchema),
  defaultValues: { email: "", password: "" },
});

---

Best practices

• Prefer strict schemas (no extra keys) for API boundaries; use .passthrough() only when you need to forward unknown keys.
• Use .default() for optional fields with a default value.
• For API/env parsing, use safeParse and handle errors; show user-friendly messages from error.issues.
• Use discriminated unions for variant payloads (e.g. events by type).
• Coerce only when safe: z.coerce.number(), z.coerce.boolean(), or custom .transform().

---

Common mistakes

• Forgetting strict: Keep TypeScript strict: true; Zod works best with it.
• Input vs output: After .transform(), use z.input<> / z.output<> if the type seen by callers differs.
• parse in hot path: Prefer validating once at boundaries (e.g. API handler, form submit) rather than on every render.
• Overly broad schema: Prefer specific types (e.g. .email(), .min()) instead of plain z.string() when the domain has rules.

---

Additional resources

• reference.md — Official Zod docs links, API sections (primitives, objects, strings, numbers, refinements, etc.), Zod Mini, ecosystem.
• Official: https://zod.dev — Introduction, API, basics, ecosystem.
• API (Zod 4): https://zod.dev/api — Full schema types and methods.
• LLMs / index: https://zod.dev/llms.txt — Structured doc for tools/agents.

License

Skill License - Free Use

This skill (the documentation, structure, and implementation) was created by Ender Puentes <Endev/> and is provided for free and open use. You are free to:

• Use this skill in any project, personal or commercial
• Modify the skill to fit your needs
• Distribute the skill to others
• Share modified versions of the skill
• Include this skill in your own skill collections

No restrictions apply – this skill is available for unrestricted use. Attribution is appreciated but not required.

Note: This skill documents and references Zod; the skill itself is an independent work. Zod is a separate work by Colin McDonnell with its own license (MIT).

Zod — Reference & Official Documentation

This file complements the zod skill with official documentation links and API sections for indexing (aligned with Zod’s public docs and llms.txt).

Official documentation (indexable)

• Home: https://zod.dev
• Introduction / basics: https://zod.dev/basics (inferring types, input vs output)
• API (Zod 4): https://zod.dev/api — Full reference for schema types and methods
• LLMs / agents: https://zod.dev/llms.txt — Structured documentation for tools and indexation

API sections (Zod 4 — from llms.txt / docs)

Use these for deep lookup; base URL is https://zod.dev/api unless noted.

• Primitives: Primitives
• Coercion: Coercion
• Literals: Literals
• Strings: Strings
• String formats: String formats, Emails, UUIDs, URLs, ISO datetimes, ISO dates, ISO times, IP addresses, IP blocks (CIDR), MAC Addresses, JWTs, Hashes, Custom formats, Template literals
• Numbers: Numbers, Integers, BigInts
• Booleans: Booleans
• Dates: Dates
• Enums: Enums, .enum, .exclude(), .extract()
• Stringbools: Stringbools
• Optionals / Nullables / Nullish: Optionals, Nullables, Nullish
• Unknown / Never: Unknown, Never
• Objects: Objects, z.strictObject, z.looseObject, .catchall(), .shape, .keyof(), .extend(), .safeExtend(), .pick(), .omit(), .partial(), .required(), Recursive objects, Circularity errors
• Arrays: Arrays
• Tuples: Tuples
• Unions: Unions, Exclusive unions (XOR), Discriminated unions
• Intersections: Intersections
• Records: Records, z.record, z.partialRecord, z.looseRecord
• Maps / Sets: Maps, Sets
• Files: Files
• Promises: Promises
• Instanceof: Instanceof
• Property: Property
• Refinements: Refinements, .refine(), error
• Transform / pipe: Transform, pipe (see API)
• Error handling: Error, ZodError, .format()

Zod Mini (tree-shakable)

• Zod Mini: https://zod.dev/packages/mini — Tree-shaking, when (not) to use, DX, backend, ZodMiniType, .parse, .check(), .register(), .brand(), .clone(def), no default locale

Ecosystem

• Ecosystem: https://zod.dev (Ecosystem section) — Form integrations (e.g. React Hook Form with zodResolver), API libraries, Zod to X, X to Zod, mocking
• React Hook Form: Use @hookform/resolvers with zodResolver(schema); type form with z.infer<typeof schema>
• tRPC: End-to-end typesafe APIs with Zod schemas

Requirements (reminder)

• TypeScript 5.5+ recommended
• strict mode enabled in tsconfig.json:

  { "compilerOptions": { "strict": true } }

Installation

Add zod via your package manager. Also available as @zod/zod on jsr.io. Zod provides an MCP server for agent/editor integration; see https://zod.dev for instructions.