zod-4

Migrate Zod schemas from v3 to v4 with updated APIs.

1|Updated Jan 18, 2026

Search Tags:#typescript #validation #migration #zod #schemas #runtime-typing

Ready to run

npx skills add https://github.com/valec3/AGENTS.md --skill zod-4-valec3

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: zod-4
Source: https://github.com/valec3/AGENTS.md/tree/main/REFERENCES/GentlemanProgramming/skill/zod-4
Command: npx skills add https://github.com/valec3/AGENTS.md --skill zod-4-valec3

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Zod v3 to v4 migrations can introduce breaking changes and inconsistent validation patterns. This Skill guides you through updating schemas to the new API surface, ensuring consistent validation behavior across the codebase.

Core Features & Use Cases

Migration guidance: convert common schemas from zod v3 to zod v4 with updated APIs.
Pattern updates: adopt new top-level validators, improved error handling, and refined object schemas.
Use Case: upgrade an existing form validation setup that uses z.string().email() and z.object({ name: z.string() }) to the v4 equivalents and verify with parse/safeParse.

Quick Start

Run through the example migration steps and apply them to a representative v3 schema to produce a v4-compatible counterpart and test with sample data.

Frequently Asked Questions about zod-4

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I migrate Zod schemas from v3 to v4?▼

To migrate Zod schemas from v3 to v4, you update existing validation patterns to the new API surface, converting object schemas, arrays, and unions to ensure consistent runtime typing and parsing behavior across your codebase.

What breaking changes do I need to address during a Zod v4 migration?▼

A Zod v4 migration requires addressing breaking changes by adopting top-level validators, explicit error handling, and updated transformations to maintain consistent validation behavior for form inputs and runtime type checks.

How do I update z.string().email() validation to Zod 4?▼

Updating z.string().email() validation to Zod 4 involves converting the schema to use the new top-level validators and explicit error handling, then verifying the updated pattern using parse or safeParse with sample data.

Does Zod 4 support object schemas, refinements, and transformations?▼

Yes, Zod 4 supports object schemas, refinements, and transformations. The migration process guides you through updating these specific schema patterns to align with the new API surface for consistent validation.

Can I test migrated Zod 4 schemas with safeParse?▼

Yes, you can test migrated Zod 4 schemas with safeParse. After updating a representative v3 schema to its v4-compatible counterpart, you apply safeParse with sample data to verify consistent validation behavior.

What are the limitations of migrating Zod schemas to v4?▼

Limitations of migrating Zod schemas to v4 include potential inconsistent validation patterns if breaking changes are not fully addressed, requiring careful updates to unions, refinements, and explicit error handling.