Convert Zod to Yup

Q: What Zod features cannot be automatically converted to Yup?

z.discriminatedUnion requires manual refactoring since Yup has no direct equivalent. z.record maps to yup.object with limited key typing. z.tuple converts to yup.array but loses per-element type safety. z.branded types have no Yup equivalent. These patterns receive TODO comments with guidance.

Q: Does Yup auto-coerce values differently than Zod?

Yes. Yup auto-coerces by default (e.g., yup.number() will coerce '42' to 42), while Zod requires explicit z.coerce.number(). After migrating from Zod to Yup, your schemas may accept inputs that were previously rejected. SchemaShift warns about this behavioral difference during migration.

Migrate Zod schemas back to Yup for legacy codebase integration, team familiarity with Yup’s API, or ecosystem requirements where Yup is the established standard. SchemaShift handles the AST-based transformation automatically.

Quick Start

Install SchemaShift globally and run the migration with a single command:

npm install -g schemashift-cli
schemashift migrate ./src -f zod -t yup

Pro+ Required

Backward migrations (Zod → Yup) require a Pro or Team license. View pricing.

Before & After

Before (Zod)

import { z } from 'zod';

const UserSchema = z.object({
  name: z.string().min(2).max(100),
  email: z.string().email(),
  age: z.number().int().min(0).optional(),
  role: z.enum(['admin', 'user', 'guest']),
  status: z.literal('active'),
  bio: z.string().nullable(),
});

type User = z.infer<typeof UserSchema>;

After (Yup)

import * as yup from 'yup';

const UserSchema = yup.object({
  name: yup.string().required().min(2).max(100),
  email: yup.string().required().email(),
  age: yup.number().integer().min(0).notRequired(),
  role: yup.mixed().oneOf(['admin', 'user', 'guest']).required(),
  status: yup.mixed().oneOf(['active']).required(),
  bio: yup.string().nullable().required(),
});

type User = yup.InferType<typeof UserSchema>;

Conversion Reference

Zod	Yup	Notes
`z.object({...})`	`yup.object({...})`	Direct mapping
`z.string()`	`yup.string().required()`	Zod is required by default; Yup needs explicit `.required()`
`z.number()`	`yup.number().required()`	Same required semantics difference
`z.boolean()`	`yup.boolean().required()`	Same required semantics difference
`.optional()`	`.notRequired()`	Yup uses `.notRequired()` instead of `.optional()`
`.nullable()`	`.nullable()`	Direct mapping
`.refine(fn, msg)`	`.test(name, msg, fn)`	Different argument order; Yup requires a test name
`z.enum(['a', 'b'])`	`yup.mixed().oneOf(['a', 'b'])`	Yup has no native enum; uses `.oneOf()`
`z.literal('val')`	`yup.mixed().oneOf(['val'])`	Expressed as single-value `.oneOf()`
`z.union([a, b])`	`yup.mixed().oneOf([...])`	Limited; works for literal unions only
`z.array(z.string())`	`yup.array().of(yup.string())`	Direct mapping with `.of()`
`z.infer<typeof S>`	`yup.InferType<typeof S>`	Type helper rewritten automatically

Edge Cases & Gotchas

z.record() → yup.object() (limited): Zod’s z.record(z.string(), z.number()) allows arbitrary keys with typed values. Yup has no direct record equivalent. SchemaShift converts to yup.object() with a TODO comment noting the limitation. You may need yup.lazy() for dynamic keys.
z.tuple() → yup.array() (limited): Zod tuples enforce per-element types (e.g., z.tuple([z.string(), z.number()])). Yup arrays cannot enforce different types per index. The migration converts to yup.array() with a TODO noting the lost type granularity.
z.discriminatedUnion() needs manual refactoring: Yup has no discriminated union. SchemaShift emits the schema with a /* TODO(schemashift): ... */ comment. Use yup.lazy() with a switch on the discriminator field as the manual replacement.
.superRefine() → .test() with different API: Zod’s .superRefine() receives a context with ctx.addIssue(). Yup’s .test() returns true/false or this.createError(). Complex refinements need manual adjustment of error reporting logic.
Yup auto-coerces (behavioral difference): Yup automatically coerces values by default — yup.number() will accept "42" and coerce it to 42. Zod does not coerce unless you use z.coerce. After migration, your schemas may accept inputs that Zod previously rejected. Add .strict() in Yup to disable coercion if needed.

Automated Migration

Run the full migration with dry-run first to preview changes:

# Preview changes without modifying files
schemashift migrate ./src -f zod -t yup --dry-run

# Run the actual migration
schemashift migrate ./src -f zod -t yup

# Export a diff for code review
schemashift migrate ./src -f zod -t yup --dry-run --output-diff changes.patch

# Verbose output with HTML report
schemashift migrate ./src -f zod -t yup -v --report html

Post-Migration Checklist

Run npm install yup if not already installed
Search for TODO(schemashift) comments and resolve manually
Update form resolvers: zodResolver → yupResolver
Test schemas that relied on Zod’s strict (non-coercing) parsing
Verify .refine() → .test() conversions return correct error messages
Check z.discriminatedUnion TODO comments and implement yup.lazy() replacements
Run npx tsc --noEmit to verify TypeScript compilation
Run your test suite to confirm validation behavior is unchanged
Consider adding .strict() to Yup schemas if coercion is unwanted

Frequently Asked Questions

Can I convert Zod schemas back to Yup automatically?

Yes. SchemaShift supports backward migration from Zod to Yup using AST-based transformations. Run schemashift migrate ./src -f zod -t yup to convert z.object, z.string, z.enum, .refine, and other Zod patterns to their Yup equivalents. This requires a Pro or Team license.

What Zod features cannot be automatically converted to Yup?

z.discriminatedUnion requires manual refactoring since Yup has no direct equivalent. z.record maps to yup.object with limited key typing. z.tuple converts to yup.array but loses per-element type safety. z.branded types have no Yup equivalent. These patterns receive TODO comments with guidance.

Does Yup auto-coerce values differently than Zod?

Yes. Yup auto-coerces by default (e.g., yup.number() will coerce "42" to 42), while Zod requires explicit z.coerce.number(). After migrating from Zod to Yup, your schemas may accept inputs that were previously rejected. SchemaShift warns about this behavioral difference during migration.

Related Guides

Ready to migrate?

Convert your Zod schemas to Yup automatically with SchemaShift.

Get SchemaShift