Get expert guidance on Zod v4 validation, schemas, and migrations
Get expert help with Zod v4 validation, schemas, and migrations from v3. Provide your code or describe what you're validating for specific guidance.
/plugin marketplace add boneskull/claude-plugins/plugin install zod@boneskull-plugins[what-you-need]Provide expert guidance on using Zod v4 validation library, including schemas, migrations from v3, and validation patterns.
/zod [optional: what you need help with]
Arguments:
what-you-need (optional): Describe what you're trying to do with Zod or paste code you need help withWhen this command is invoked:
Load the zod-v4 skill from skills/zod-v4/SKILL.md
If the user provided context, analyze their needs and:
references/If no context was provided, offer to help by:
Always emphasize key Zod v4 patterns:
.safeParse() for user input (never crash on bad data)z.email() not z.string().email() (v4 breaking change)error parameter not message for custom errors (v4 breaking change)z.strictObject() instead of .strict() (v4 breaking change)z.infer<typeof schema> for TypeScript typesWhen discussing migrations from v3:
references/migration-from-v3.mdWith context - creating a schema:
User: /zod I need to validate user registration with email, password, and age
Agent: Here's a Zod v4 schema for user registration:
\`\`\`typescript
import { z } from 'zod/v4';
const registrationSchema = z.object({
email: z.email(), // v4: top-level format validator
password: z
.string()
.min(8, { error: 'Password must be at least 8 characters' })
.regex(/[A-Z]/, { error: 'Must contain uppercase letter' })
.regex(/[0-9]/, { error: 'Must contain number' }),
age: z.number().int().positive().min(13, {
error: 'Must be at least 13 years old',
}),
});
// Type inference
type Registration = z.infer<typeof registrationSchema>;
// Safe parsing
const result = registrationSchema.safeParse(userData);
if (!result.success) {
// Handle validation errors
console.error(result.error.issues);
} else {
// result.data is fully typed and validated
createUser(result.data);
}
\`\`\`
Key v4 features used:
- `z.email()` - top-level format validator (breaking change from v3)
- `error` parameter - replaces `message` from v3
- `.safeParse()` - never throws, always handle errors gracefully
- `z.infer` - automatic TypeScript types from your schema
With context - migration:
User: /zod How do I migrate this v3 code?
z.string().email().min(5, { message: 'Too short' })
Agent: Here's the Zod v4 equivalent:
\`\`\`typescript
// ❌ Zod v3
z.string().email().min(5, { message: 'Too short' })
// ✅ Zod v4
z.email().min(5, { error: 'Too short' })
\`\`\`
Two breaking changes here:
1. **String formats** moved to top-level: `z.email()` instead of `z.string().email()`
2. **Error messages** now use `error` parameter instead of `message`
This applies to all format validators:
- `z.email()` not `z.string().email()`
- `z.url()` not `z.string().url()`
- `z.uuid()` not `z.string().uuid()`
- etc.
See the migration guide for all breaking changes: [references/migration-from-v3.md]
With context - debugging:
User: /zod Why is my validation failing?
const schema = z.object({ name: z.string() }).strict();
Agent: In Zod v4, the `.strict()` method has been removed. Use `z.strictObject()` instead:
\`\`\`typescript
// ❌ Zod v3 syntax (won't work in v4)
z.object({ name: z.string() }).strict()
// ✅ Zod v4 syntax
z.strictObject({ name: z.string() })
\`\`\`
Similarly:
- Use `z.looseObject()` instead of `.passthrough()`
- Use shape spreading for extending: `z.object({ ...Base.shape, newField: z.string() })`
This is one of 9 major breaking changes in v4. Want to see the complete list?
Without context:
User: /zod
Agent: I can help you with Zod v4! What are you trying to do?
Common scenarios:
- **Creating schemas** - validating forms, API responses, configs, user input
- **Migrating from v3** - upgrading existing Zod code to v4
- **Type inference** - getting TypeScript types from your schemas
- **Custom validation** - adding business logic and custom error messages
- **Debugging** - fixing validation errors or understanding failures
- **Advanced patterns** - recursive schemas, discriminated unions, transforms
You can also paste your existing code and I'll help you improve it or migrate it to v4!
For reference, I have access to:
- Complete v3 → v4 migration guide
- Full v4 API reference
- Real-world validation patterns