zod-4_skill

Overview

This skill documents Zod 4 schema validation patterns and highlights breaking changes from Zod 3. It provides concise examples for primitives, objects, arrays, unions, transformations, refinements, coercion, and error handling. Use it as a quick reference when upgrading or writing Zod v4 validators.

How this skill works

The skill shows idiomatic Zod 4 constructs and replacement patterns for deprecated v3 methods. It demonstrates top-level validators (z.email, z.uuid, z.url), object options for errors, coercion utilities, preprocess/transform hooks, and refined validations with superRefine. Examples include parse vs safeParse, custom error maps, and integration with React Hook Form.

When to use it

• When migrating from Zod v3 to Zod v4 and you need exact replacements for removed APIs.
• When writing new schemas that benefit from top-level validators and improved error options.
• When you need safe parsing, coercion from strings, or transforming input during validation.
• When implementing complex cross-field validation using superRefine.
• When integrating Zod with form libraries like React Hook Form via zodResolver.

Best practices

• Prefer top-level validators (z.email(), z.uuid(), z.url()) instead of chaining on z.string().
• Use z.object(schema, { error: '...' }) to supply object-level errors instead of required_error from v3.
• Use z.coerce.* for safe coercion from strings and z.preprocess for custom pre-parsing logic.
• Return structured issues via superRefine for cross-field checks and use ctx.addIssue for granular errors.
• Use safeParse in runtime flows to avoid thrown exceptions and inspect result.error.issues for user messages.

Example use cases

• Validate incoming API payloads with z.object and z.record for dynamic keys.
• Define form schemas and plug into React Hook Form using zodResolver for typed forms.
• Coerce query string params to numbers or dates with z.coerce.number() and z.coerce.date().
• Create discriminated unions for efficient runtime branching on a status or type field.
• Enforce password rules and confirm-password checks using refine/superRefine.