Zod

IMPORTANT: Your training data about

zod

When to Use Zod

Zod is for runtime type validation — parsing untrusted data at system boundaries (API input, form data, env vars, external services). For compile-time-only types, plain TypeScript is sufficient.

Rule Categories by Priority

parse-

schema-

refine-

error-

perf-

migrate-

pattern-

arch-

observe-

Quick Reference

1. Parsing & Type Safety (CRITICAL)

• parse-use-safeParse

  — Use

  safeParse()

  for user input instead of

  parse()

  which throws

• parse-async-required

  — Must use

  parseAsync()

  /

  safeParseAsync()

  when schema has async refinements

• parse-infer-types

  — Use

  z.infer<typeof Schema>

  for output types; never manually duplicate types

2. Schema Design (CRITICAL)

• schema-object-unknowns

  —

  z.object()

  strips unknown keys; use

  strictObject

  or

  looseObject

• schema-union-discriminated

  — Use

  z.discriminatedUnion()

  for tagged unions, not

  z.union()

• schema-coercion-pitfalls

  —

  z.coerce.boolean()

  makes

  "false"

  →

  true

  ; use

  z.stringbool()

• schema-recursive-types

  — Use getter pattern for recursive schemas;

  z.lazy()

  is removed in v4

3. Refinements & Transforms (HIGH)

• refine-never-throw

  — Never throw inside

  .refine()

  or

  .transform()

  ; use

  ctx.addIssue()

• refine-vs-transform

  —

  .refine()

  for validation,

  .transform()

  for conversion,

  .pipe()

  for staging

• refine-cross-field

  —

  .superRefine()

  on parent object for cross-field validation with

  path

4. Error Handling (HIGH)

• error-custom-messages

  — Use v4

  error

  parameter;

  required_error

  /

  invalid_type_error

  are removed

• error-formatting

  —

  z.flattenError()

  for forms,

  z.treeifyError()

  for nested;

  formatError

  deprecated

• error-input-security

  — Never use

  reportInput: true

  in production; leaks sensitive data

5. Performance & Composition (MEDIUM)

• perf-extend-spread

  — Use

  { ...Schema.shape }

  spread over chained

  .extend()

  for large schemas

• perf-reuse-schemas

  — Define once, derive with

  .pick()

  ,

  .omit()

  ,

  .partial()

• perf-zod-mini

  — Use

  zod/v4/mini

  (1.88kb) for bundle-critical client apps

6. v4 Migration (MEDIUM)

• migrate-string-formats

  — Use

  z.email()

  ,

  z.uuid()

  ,

  z.url()

  not

  z.string().email()

• migrate-native-enum

  — Use unified

  z.enum()

  for TS enums;

  z.nativeEnum()

  is removed

• migrate-error-api

  — Use

  error

  parameter everywhere;

  message

  ,

  errorMap

  are removed

7. Advanced Patterns (MEDIUM)

• pattern-branded-types

  —

  .brand<"Name">()

  for nominal typing (USD vs EUR)

• pattern-codecs

  —

  z.codec()

  for bidirectional transforms (parse + serialize)

• pattern-pipe

  —

  .pipe()

  for staged parsing (string → number → validate range)

8. Architecture & Boundaries (CRITICAL/HIGH)

• arch-boundary-parsing

  — Parse at system boundaries (API handler, env, form, fetch); pass typed data to domain logic

• arch-schema-organization

  — Co-locate schemas with their boundary layer; domain types use

  z.infer

• arch-schema-versioning

  — Additive changes only for non-breaking evolution; new fields use

  .optional()

9. Observability (HIGH/MEDIUM)

• observe-structured-errors

  — Use

  z.flattenError()

  for compact structured logs with request correlation IDs

• observe-error-metrics

  —

  trackedSafeParse()

  wrapper to increment counters per schema and field on failure

Schema Types Quick Reference

z.string()

z.number()

z.int()

z.float()

z.boolean()

z.bigint()

z.date()

z.undefined()

z.null()

z.void()

z.any()

z.unknown()

z.never()

z.literal("foo")

z.literal(42)

z.enum(["a", "b"])

z.enum(TSEnum)

z.email()

z.url()

z.uuid()

z.stringbool()

z.iso.datetime()

z.file()

z.json()

z.array(schema)

z.tuple([a, b])

z.object({})

z.strictObject({})

z.looseObject({})

z.record(keySchema, valueSchema)

z.map(keySchema, valueSchema)

z.set(schema)

z.union([a, b])

z.discriminatedUnion("key", [...])

z.intersection(a, b)

How to Use

Read individual rule files for detailed explanations and code examples:

rules/parse-use-safeParse.md
rules/schema-object-unknowns.md

Each rule file contains:

• Brief explanation of why it matters
• Incorrect code example with explanation
• Correct code example with explanation
• Additional context and decision tables

References

references/schema-types.md

references/parsing-and-inference.md

references/objects-and-composition.md

references/refinements-and-transforms.md

references/error-handling.md

references/advanced-features.md

references/anti-patterns.md

references/boundary-architecture.md

references/linter-and-ci.md

Full Compiled Document

For the complete guide with all rules expanded:

AGENTS.md