zod-v4

name	zod-v4
description	Zod v4 TypeScript schema design, Zod 3 to 4 migration, validation boundaries, errors, codecs, JSON Schema/OpenAPI, metadata, Zod Mini/Core, RHF/tRPC/Hono/Next integrations, and rule-aware audits for Zod 4.4.3.

Zod v4

Rule-first Zod v4.4.3 guidance for TypeScript. Start with the highest-risk matching rule, then load the linked reference only when deeper API detail is needed.

Quick Start

bun add zod@^4.4.3

import { z } from "zod";

const User = z.object({
  name: z.string().min(1, { error: "Required" }),
  email: z.email({ error: "Invalid email" }),
});

type User = z.infer<typeof User>;

Route By Task

Task	Start Here
v3 migration or deprecated API cleanup	rules/_index.md, then references/migration-v3-to-v4.md
User input, env, HTTP, DB, queue, or JSON boundaries	parse-*, schema-*, and references/codecs-v4.md
Current schema APIs, string formats, records, template literals, XOR, defaults	references/schema-surface-v4.md
UI/API/CLI error messages	error-*, migrate-error-*, and references/errors-v4.md
Object composition, strictness, or refined schemas	object-* rules
JSON Schema/OpenAPI export	jsonschema-*, meta-*, and references/json-schema-v4.md
Bidirectional wire/internal transforms	codec-* and references/codecs-v4.md
React Hook Form, tRPC, Hono, or Next.js actions	references/ecosystem-*.md
Zod Mini, package exports, or library-author work	references/package-surfaces-v4.md
Repo audit before a migration	references/audit.md and scripts/zod-audit.ts

Priority Rules

1. Validate at boundaries: use safeParse for untrusted input, parseAsync for async refinements/transforms, and never trust JSON.parse output.
2. Prefer current v4 APIs: top-level string formats, z.enum, z.object plus z.strictObject or z.looseObject, unified { error }, top-level error formatters, and z.toJSONSchema.
3. Avoid false enforcement: default imports, namespace root imports, and one-arg z.record(valueSchema) are valid in Zod 4.4.3; treat them as local style or migration-advisory findings, not package-invalid code.
4. Use codecs when direction matters: prefer z.codec, z.decode, z.encode, and z.invertCodec for reversible wire/internal mappings.
5. Use zod/v4/core only for library tooling: app code normally imports from zod; bundle-sensitive app code can use zod/mini; schema tooling and library adapters should read references/package-surfaces-v4.md.

Rule Categories

Priority	Category	Prefix
1	Migration + deprecations	migrate-
2	Parsing + boundaries	parse-
3	Error handling	error-
4	Objects + composition	object-
5	Schema definitions	schema-
6	Metadata + registries	meta-
7	JSON Schema/OpenAPI	jsonschema-
8	Codecs	codec-
9	Package surfaces	package-

Start with rules/_index.md. Each rule file has the failure mode, compact bad/good examples, and linked references when nuance matters.

Automation

Resolve skill_dir as the directory containing this skill before running bundled scripts.

Zod Audit

Run the Zod-specific report-only scanner:

bun "$skill_dir/scripts/zod-audit.ts" --root . --format text

Useful commands:

bun "$skill_dir/scripts/zod-audit.ts" --list-rules
bun "$skill_dir/scripts/zod-audit.ts" --list-checks
bun "$skill_dir/scripts/zod-audit.ts" --explain migrate-top-level-string-formats

Use --fail-on warn|error|info only after reviewing whether advisory rules are appropriate for the target repo.

AI Stack Scanner

Use the shared dependency-free scanner for broad AI-stack migration signals:

python3 "$skill_dir/scripts/ai_stack_scan.py" --root . --family zod-v4 --pretty

Treat scanner output as private local evidence. Verify each signal against the current code and Zod docs/source before editing.

Rule Maintenance

bun "$skill_dir/scripts/build-rules-index.ts"
bun "$skill_dir/scripts/check-skill-integrity.ts"

Schema Runner

Load a schema from a local module and exercise parse, decode/encode, or JSON Schema behavior:

bun "$skill_dir/scripts/zod-run.ts" --module src/schemas/user.ts --export User --mode safeParse --input '{"name":"A","email":"[e-mail]"}'
bun "$skill_dir/scripts/zod-run.ts" --module src/schemas/date.ts --export IsoDate --mode encode --input '"2026-05-13T00:00:00.000Z"'
bun "$skill_dir/scripts/zod-run.ts" --module src/schemas/user.ts --export User --mode toJSONSchema --io input --target openapi-3.0

zod-run.ts imports the target module, so avoid modules with heavy side effects.

References

• Reference router: references/index.md
• Migration checklist: references/migration-v3-to-v4.md
• Schema surface highlights: references/schema-surface-v4.md
• Errors and formatting: references/errors-v4.md, references/error-formatting-v4.md
• Metadata and JSON Schema: references/metadata-registries-v4.md, references/json-schema-v4.md
• Codecs: references/codecs-v4.md
• Package surfaces, Mini, Core, and library authors: references/package-surfaces-v4.md
• Ecosystem: references/ecosystem-react-hook-form.md, references/ecosystem-trpc.md, references/ecosystem-hono.md, references/ecosystem-nextjs-server-actions.md
• Audit guide: references/audit.md
• Rule template: assets/templates/rule-template.md