zod

Original：🇺🇸 English
Translated

Portable Zod schema design and validation guidance. Default to `zod/mini` for new work and preserve established classic `zod` surfaces. Use when Codex needs to create, extend, refactor, or review Zod schemas; choose strict or loose object contracts; model nullability, unions, intersections, recursion, or runtime-validated values; or debug surprising Zod behavior and serialization boundaries.

2installs
Sourcecorneliusio/skills
Added on

NPX Install

npx skill4agent add corneliusio/skills zod

Tags

Translated version includes tags in frontmatter
zod-schemaschema-validationruntime-contractszod-minicode-review

SKILL.md Content

View Translation Comparison →

Zod

Specification

The words 
MUST
, 
MUST NOT
, 
REQUIRED
, 
SHALL
, 
SHALL NOT
, 
SHOULD
, 
SHOULD NOT
, 
RECOMMENDED
, 
MAY
, and 
OPTIONAL
are interpreted as described in RFC 2119.
Use this skill to design or review Zod schemas.
  • 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.
bash
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.