Zod

Specification

MUST

MUST NOT

REQUIRED

SHALL

SHALL NOT

SHOULD

SHOULD NOT

RECOMMENDED

MAY

OPTIONAL

• Default to

  zod/mini

  for new work.
• Preserve an existing classic

  zod

  surface when the file or repo already established it.
• Read references/variant-guide.md when the import or API surface is unclear, or when you need the exact mini-vs-classic rules.
• Read references/patterns.md for compact

  zod/mini

  -first examples.

Workflow

1. Detect the local surface.

rg -n "from 'zod/mini'|from \"zod/mini\"|from 'zod'|from \"zod\"" .
rg -n '"zod"' package.json bun.lock pnpm-lock.yaml package-lock.json yarn.lock

• Stay on the file or repo's established surface.
• If none exists, start with

  import * as z from 'zod/mini'

  .
• Do not migrate between

  zod

  and

  zod/mini

  unless the user explicitly asks.

1. Define the boundary.

• Parse untrusted input at I/O boundaries.
• Use

  safeParse

  for expected invalid input.
• Use

  parse

  when invalid input should throw.

1. Choose exact contract semantics.

• Prefer

  z.strictObject(...)

  for internal contracts.
• Use

  z.looseObject(...)

  only when extra keys are intentional.
• Choose

  optional

  ,

  nullable

  ,

  null

  , and

  undefined

  explicitly.

1. Compose.

• Prefer base schemas plus

  intersection

  ,

  union

  , and literal tags.
• Use

  lazy

  for recursion.
• Keep

  custom

  , manual

  any

  , and similar escape hatches narrow.

1. Normalize only when useful.

• Normalize messy raw values before parsing the narrower schema the caller needs.
• Re-parse at the consumption boundary only when that local contract is stricter than the upstream payload contract.

1. Check serialization boundaries.

• Keep returned, stored, and transmitted payloads data-only.
• Keep functions, helper objects, closures, and other behavior-bearing values local.

Rules

• Treat Zod as a runtime contract system, not just a typing tool.
• Prefer composition over mutation-style schema building.
• Prefer readable operational errors over raw issue dumps.