Zod Development

Zod is a TypeScript-first schema declaration and validation library. Use this skill when defining schemas, validating data, transforming inputs, or working with type-safe APIs.

When to Apply

Reference this skill when:

• Defining schemas for runtime validation
• Creating type-safe API boundaries
• Transforming and coercing data
• Generating JSON Schema from TypeScript types
• Validating form inputs, environment variables, or API responses
• Working with Zod v4’s new features (Mini, Core, Codecs)

Quick Reference

Primitive Types

String Formats

String Methods

Number Methods

Coercion

Object Methods

Array Methods

Set Methods

Union Types

Optionality

Validation & Transforms

Parsing Methods

Error Handling

Metadata

JSON Schema

Codecs (v4)

Codecs are bi-directional transformations. You define them using z.codec(inputSchema, outputSchema, { decode, encode }):

const stringToDate = z.codec(
  z.iso.datetime(),  // input: ISO date string
  z.date(),          // output: Date object
  {
    decode: (isoString) => new Date(isoString),
    encode: (date) => date.toISOString()
  }
)

// Forward: string → Date
stringToDate.decode("2024-01-15T10:30:00.000Z") // => Date

// Backward: Date → string  
stringToDate.encode(new Date()) // => "2024-01-15T10:30:00.000Z"

Use .decode() for forward processing and .encode() for backward processing.

v4 Features

Core Concepts

1. Schema Definition

import { z } from "zod"

const User = z.object({
  id: z.string().uuid(),
  name: z.string().min(1).max(100),
  email: z.string().email(),
  age: z.number().int().nonnegative().optional(),
  role: z.enum(["admin", "user", "guest"]).default("user"),
  createdAt: z.coerce.date()
})

type User = z.infer<typeof User>

2. Parsing & Validation

// Parse (throws on error)
const user = User.parse(data)

// Safe parse (returns result)
const result = User.safeParse(data)
if (result.success) {
  console.log(result.data)
} else {
  console.log(result.error)
}

// Async parsing
const asyncUser = await User.parseAsync(data)

3. Transformations

const TrimmedString = z.string().trim().toLowerCase()

const DateFromString = z.string().datetime().transform(val => new Date(val))

const FormattedUser = User.transform(user => ({
  ...user,
  displayName: `${user.name} <${user.email}>`
}))

4. Composition

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

// Discriminated Union
const Event = z.discriminatedUnion("type", [
  z.object({ type: z.literal("click"), x: z.number(), y: z.number() }),
  z.object({ type: z.literal("keypress"), key: z.string() })
])

// Intersection
const Combined = z.intersection(BaseSchema, ExtraSchema)

5. Error Customization

const Password = z.string()
  .min(8, "Password must be at least 8 characters")
  .max(100, "Password is too long")
  .regex(/[A-Z]/, "Must contain uppercase letter")

// Per-parse error handling
const result = schema.safeParse(data, {
  error: (issue) => `Custom: ${issue.message}`
})

Common Patterns

API Response Schema

const ApiResponse = <T extends z.ZodTypeAny>(data: T) =>
  z.object({
    success: z.boolean(),
    data: data.optional(),
    error: z.string().optional()
  })

Environment Variables

const Env = z.object({
  NODE_ENV: z.enum(["development", "production", "test"]),
  DATABASE_URL: z.string().url(),
  PORT: z.coerce.number().int().min(1).max(65535).default(3000)
})

const env = Env.parse(process.env)

Recursive Schema

const Node: z.ZodType<TreeNode> = z.lazy(() =>
  z.object({
    value: z.string(),
    children: z.array(Node).optional()
  })
)

Form Validation

const LoginForm = z.object({
  email: z.string().email("Invalid email"),
  password: z.string().min(8, "Password too short"),
  rememberMe: z.boolean().default(false)
})

type LoginInput = z.infer<typeof LoginForm>

How to Work

1. Import Zod: import { z } from "zod"
2. Define schema: Use primitives, objects, and composition
3. Add constraints: Chain methods like .min(), .max(), .email()
4. Parse data: Use .parse() or .safeParse()
5. Handle errors: Check .success or use error formatting
6. Transform if needed: Use .transform() for data transformation

v4 Migration Notes

• z.custom() now uses z.custom<T>(fn) syntax
• .refine() returns schema directly (no wrapping)
• Error messages use new formatting system
• Use zod/mini for optimal tree-shaking

Related Resources

• Official Docs: https://zod.dev/
• API Reference: https://zod.dev/api
• Ecosystem: https://zod.dev/ecosystem
• Migration Guide: https://zod.dev/v4/changelog

Related Skills

• typescript – TypeScript best practices
• arktype – Alternative validation library