git:20260512.8418464 to git:20260611.54152bc

- description: Expert guidance for Zod v4 schema validation in TypeScript. Use when designing schemas, migrating from Zod 3, handling validation errors, generating JSON Schema/OpenAPI, using codecs/transforms, or integrating with React Hook Form, tRPC, Hono, or Next.js. Covers all Zod v4 APIs including top-level string formats, strictObject/looseObject, metadata, registries, branded types, and recursive schemas.

- # Zod v4 Schema Validation

- pnpm add zod@^4.3.5

- ```typescript

- import { z } from 'zod';

- // Define schema

- name: z.string().min(1),

- email: z.email(),

- age: z.number().positive(),

- // Parse (throws on error)

- const user = User.parse({ name: "Alice", email: "alice@example.com", age: 30 });

-

- // Safe parse (returns result)

- const result = User.safeParse(data);

- if (result.success) {

- result.data; // validated

- } else {

- console.log(z.prettifyError(result.error));

- }

-

- // Type inference

- ## Versioning + Imports (v4.3.5)

-

- - Use `import { z } from "zod"` for v4 (package root now exports v4).

- - Use `import * as z from "zod/mini"` for Zod Mini.

- - Use `import * as z from "zod/v3"` only if you must stay on v3.

-

- ## Workflow: Determine Task Type

-

- **Designing new schemas?**

- → Read [API Reference](references/api-reference.md)

-

- **Migrating from Zod 3?**

- → Read [Migration Guide](references/migration-guide.md)

-

- **Working with codecs, errors, JSON Schema, or metadata?**

- → Read [Advanced Features](references/advanced-features.md)

-

- **Integrating with frameworks (RHF, tRPC, Hono, Next.js)?**

- → Read [Ecosystem Patterns](references/ecosystem-patterns.md)

-

- ---

-

- ## Key v4 Concepts

-

- ### Top-Level String Formats

-

- v4 moved string validators to top-level functions:

-

- ```typescript

- // v4 style (preferred)

- z.email()

- z.uuid()

- z.url()

- z.ipv4()

- z.ipv6()

- z.iso.date()

- z.iso.datetime()

-

- // v3 style (deprecated but works)

- z.string().email()

- ```

-

- ### Object Variants

-

- ```typescript

- z.object({}) // Allows unknown keys (default)

- z.strictObject({}) // Rejects unknown keys

- z.looseObject({}) // Explicitly allows unknown keys

- ```

-

- ### Unified Error Parameter

-

- ```typescript

- // String message

- z.string().min(5, { error: "Too short" });

-

- // Function for dynamic messages

- z.string({

- error: (iss) => iss.input === undefined ? "Required" : "Invalid"

- });

- ```

-

- ### Type Inference

-

- ```typescript

- const Schema = z.object({ name: z.string() });

- type Schema = z.infer<typeof Schema>;

-

- // For transforms, get input/output separately

- const Transformed = z.string().transform(s => s.length);

- type Input = z.input<typeof Transformed>; // string

- type Output = z.output<typeof Transformed>; // number

- ```

-

- ---

-

- ## Common Patterns

-

- ### Discriminated Unions

-

- ```typescript

- const Event = z.discriminatedUnion("type", [

- z.object({ type: z.literal("click"), x: z.number(), y: z.number() }),

- z.object({ type: z.literal("keypress"), key: z.string() }),

- ]);

- ```

-

- ### Exhaustive Records

-

- ```typescript

- const Status = z.enum(["pending", "active", "done"]);

-

- // All keys required

- z.record(Status, z.number()) // { pending: number; active: number; done: number }

-

- // Keys optional

- z.partialRecord(Status, z.number()) // { pending?: number; active?: number; done?: number }

- ```

-

- ### Recursive Schemas

-

- ```typescript

- const Category = z.object({

- name: z.string(),

- get subcategories() { return z.array(Category) }

- });

- ```

-

- ### Branded Types

-

- ```typescript

- const UserId = z.string().brand<"UserId">();

- const PostId = z.string().brand<"PostId">();

-

- type UserId = z.infer<typeof UserId>;

- // Cannot assign UserId to PostId

- ```

-

- ### Transforms and Pipes

-

- ```typescript

- // Transform

- z.string().transform(s => s.toUpperCase())

-

- // Pipe (chain schemas)

- z.pipe(

- z.string(),

- z.coerce.number(),

- z.number().positive()

- )

- ```

-

- ### Default Values

-

- ```typescript

- // Output default (v4)

- z.string().default("guest")

-

- // Input default (pre-transform)

- z.string().transform(s => s.toUpperCase()).prefault("hello")

- // Missing => "HELLO"

- ```

-

- ---

-

- ## Error Handling

-

- ### Pretty Print

- ```typescript

- const result = schema.safeParse(data);

- if (!result.success) {

- console.log(z.prettifyError(result.error));

- // ✖ Invalid email

- // → at email

- }

- ```

- ### Flat Structure (Forms)

- ```typescript

- const flat = z.flattenError(result.error);

- // { formErrors: [], fieldErrors: { email: ["Invalid email"] } }

- ```

- ### Tree Structure (Nested)

- ```typescript

- const tree = z.treeifyError(result.error);

- // { properties: { email: { errors: ["Invalid email"] } } }

- ```

- ---

- ## JSON Schema / OpenAPI

- ```typescript

- const schema = z.object({

- name: z.string(),

- email: z.email(),

- }).meta({ id: "User", title: "User" });

- // Generate JSON Schema

- const jsonSchema = z.toJSONSchema(schema);

- // For OpenAPI 3.0

- z.toJSONSchema(schema, { target: "openapi-3.0" });

- // Using registry for multiple schemas

- z.globalRegistry.add(schema, schema.meta());

- const allSchemas = z.toJSONSchema(z.globalRegistry);

- ---

-

- ## v3 to v4 Migration Quick Reference

-

- | v3 | v4 |

- |----|----|

- | `z.string().email()` | `z.email()` |

- | `z.nativeEnum(MyEnum)` | `z.enum(MyEnum)` |

- | `{ message: "..." }` | `{ error: "..." }` |

- | `.strict()` | `z.strictObject({})` |

- | `.passthrough()` | `z.looseObject({})` |

- | `.merge(other)` | `.extend(other.shape)` |

- | `z.record(valueSchema)` | `z.record(z.string(), valueSchema)` |

- | `.deepPartial()` | Nest `.partial()` manually |

- | `error.format()` | `z.treeifyError(error)` |

- | `error.flatten()` | `z.flattenError(error)` |

-

- ### Breaking Changes

-

- - **Numbers**: No `Infinity`, stricter `.safe()` and `.int()`

- - **UUID**: RFC 4122 compliant (use `z.guid()` for permissive)

- - **Defaults in optional**: `z.string().default("x").optional()` now applies default

- - **z.unknown()**: No longer implicitly optional

- - **Error precedence**: Schema-level wins over global

-

- Run codemod: `npx zod-v3-to-v4`

-

- ---

-

- ## Framework Integration Quick Start

-

- ### React Hook Form

-

- ```typescript

- import { zodResolver } from '@hookform/resolvers/zod';

- const { register, handleSubmit, formState: { errors } } = useForm({

- resolver: zodResolver(schema),

- });

- ### tRPC

-

- ```typescript

- publicProcedure

- .input(z.object({ id: z.string() }))

- .query(({ input }) => getById(input.id))

- ```

- ### Hono

- ```typescript

- import { zValidator } from '@hono/zod-validator';

- app.post('/users', zValidator('json', schema), (c) => {

- const data = c.req.valid('json');

- });

- ### Next.js Server Actions

- ```typescript

- 'use server';

- const result = schema.safeParse(Object.fromEntries(formData));

- if (!result.success) {

- return { errors: z.flattenError(result.error).fieldErrors };

- }

- ## Offline Stack Scanner

- Run the local scanner before Zod migrations or validation reviews:

- python3 skills/zod-v4/scripts/ai_stack_scan.py --root <repo> --pretty

- It emits `ai_stack_scan.v1`, uses no network by default, skips symlinks, and

- flags likely Zod v4 migration signals such as pre-v4 dependency specs,

- deprecated string-format methods, legacy error parameters, `z.nativeEnum`, and

- `error.errors`. Verify each signal against current Zod docs/source before

- editing. Keep full scanner JSON local; share only specific redacted signals

- externally.

-

- ---

- ## Reference Files

- - [API Reference](references/api-reference.md) - All schema types, methods, and validation APIs

- - [Advanced Features](references/advanced-features.md) - Codecs, error handling, metadata, JSON Schema

- - [Migration Guide](references/migration-guide.md) - Complete v3 to v4 migration reference

- - [Ecosystem Patterns](references/ecosystem-patterns.md) - Framework integrations and organization patterns