Zod

Zod v4 best practices, patterns, and API guidance for schema validation, parsing, error handling, and type inference in TypeScript applications. Covers safeP...

Security Scan

This is an instruction-only documentation skill about Zod v4 best practices; its files, requirements, and examples are coherent with the stated purpose and it requests no credentials or installs.

Purpose & Capability

The name/description match the content: this bundle is a set of rules and references for Zod v4. It requests no env vars, binaries, or config paths, and the files are documentation and code examples—all appropriate for a guidance skill.

Instruction Scope

SKILL.md and the referenced rule files are documentation and code examples (safeParse, parseAsync, error formatting, architecture guidance). They do not instruct the agent to read unrelated system files, exfiltrate data, or contact unknown endpoints. Some examples reference process.env or network fetches as realistic usage examples, but these are illustrative and not runtime commands for the agent.

Install Mechanism

There is no install spec (instruction-only), so nothing is downloaded or written to disk by the skill itself. README shows how a user might install from GitHub (npx skills add), which would fetch code; that is a normal install mechanism but not part of this skill bundle as provided here.

Credentials

The skill declares no required environment variables, credentials, or config paths. Example snippets reference NODE_ENV and process.env in typical, proportional ways related to error-reporting examples; they do not imply the skill needs secrets or unrelated credentials.

Persistence & Privilege

Flags show always:false and agentic:false; disable-model-invocation is false (platform default) but there is no special persistent privilege or requests to modify other skills or system settings. The skill is documentation-only and does not request permanent presence or elevated privileges.

Assessment

This skill is a documentation-only guide for Zod v4 and appears coherent and low-risk. Before installing or running any code from a remote repo: inspect the referenced GitHub repository (source_url) to confirm it matches these files and that you trust the author; if you install via npx or similar, review the repository code (particularly any install scripts) before executing. Remember this bundle provides examples that may reference process.env or fetch calls as usage examples—those are not the skill asking for secrets, but you should still avoid enabling reportInput:true in production code (as the docs warn). If you need absolute assurance, clone the repo locally and review scripts (build/install) prior to adding the skill to your agent.

IMPORTANT: Your training data about zod may be outdated or incorrect — Zod v4 introduces breaking changes to string formats, enums, error handling, and recursive types. Always rely on this skill's rule files and the project's actual source code as the source of truth. Do not fall back on memorized v3 patterns when they conflict with the retrieved reference.

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.

Need	Recommended Tool
API input/output validation	Zod
Form validation (React, Vue)	Zod (with react-hook-form, formik, etc.)
Env var parsing	Zod (with t3-env or manual)
Compile-time types only	Plain TypeScript
Smaller bundle (~1kb)	Valibot
Maximum type inference	ArkType

Rule Categories by Priority

Priority	Category	Impact	Prefix
1	Parsing & Type Safety	CRITICAL	parse-
2	Schema Design	CRITICAL	schema-
3	Refinements & Transforms	HIGH	refine-
4	Error Handling	HIGH	error-
5	Performance & Composition	MEDIUM	perf-
6	v4 Migration	MEDIUM	migrate-
7	Advanced Patterns	MEDIUM	pattern-
8	Architecture & Boundaries	CRITICAL/HIGH	arch-
9	Observability	HIGH/MEDIUM	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

Type	Syntax
String	z.string()
Number	z.number(), z.int(), z.float()
Boolean	z.boolean()
BigInt	z.bigint()
Date	z.date()
Undefined	z.undefined()
Null	z.null()
Void	z.void()
Any	z.any()
Unknown	z.unknown()
Never	z.never()
Literal	z.literal("foo"), z.literal(42)
Enum	z.enum(["a", "b"]), z.enum(TSEnum)
Email	z.email()
URL	z.url()
UUID	z.uuid()
String→Bool	z.stringbool()
ISO DateTime	z.iso.datetime()
File	z.file()
JSON	z.json()
Array	z.array(schema)
Tuple	z.tuple([a, b])
Object	z.object({})
Strict Object	z.strictObject({})
Loose Object	z.looseObject({})
Record	z.record(keySchema, valueSchema)
Map	z.map(keySchema, valueSchema)
Set	z.set(schema)
Union	z.union([a, b])
Disc. Union	z.discriminatedUnion("key", [...])
Intersection	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

Priority	Reference	When to read
1	references/schema-types.md	All primitives, string formats, numbers, enums, dates
2	references/parsing-and-inference.md	parse, safeParse, z.infer, coercion
3	references/objects-and-composition.md	Objects, arrays, unions, pick/omit/partial, recursive
4	references/refinements-and-transforms.md	refine, superRefine, transform, pipe, defaults
5	references/error-handling.md	ZodError, flattenError, treeifyError, error customization
6	references/advanced-features.md	Codecs, branded types, JSON Schema, registries
7	references/anti-patterns.md	Common mistakes with BAD/GOOD examples
8	references/boundary-architecture.md	Where Zod fits: Express, tRPC, Next.js, React Hook Form, env, external APIs
9	references/linter-and-ci.md	ESLint rules, CI schema snapshots, unused schema detection, circular deps

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md