zod-validation

Zod v4 Validation Reference

v4 vs v3 Key Differences (IMPORTANT)

Area	v3	v4
Error params	message, invalid_type_error, required_error	Single error param
Native enum	z.nativeEnum(Enum)	z.enum(Enum) (absorbed)
Strict object	.strict()	z.strictObject({}) or .strict() (both work)
Passthrough	.passthrough()	z.looseObject({}) or .passthrough() (both work)
Deep partial	.deepPartial()	Removed — use nested .optional()
Type generics	ZodType<O, D, I> (3 params)	ZodType<O, I> (2 params)
Infinite numbers	Passed z.number()	Now rejected
_def internal	schema._def	schema._zod.def

Type Inference

const Schema = z.object({ name: z.string(), age: z.number().optional() });

type Input  = z.input<typeof Schema>;   // before coercion/transform
type Output = z.output<typeof Schema>;  // after coercion/transform (same as z.infer)
type T      = z.infer<typeof Schema>;   // alias for z.output

Use z.input for form data (raw), z.output / z.infer for processed data.

Parse Patterns

// Throws ZodError on failure
const data = Schema.parse(input);

// Safe — always returns, never throws
const result = Schema.safeParse(input);
if (result.success) {
  result.data;   // typed output
} else {
  result.error;  // ZodError (NOTE: ZodError no longer extends Error in v4)
}

Prefer safeParse in request handlers and form submission paths.

Custom Error Messages (v4 API)

// v4: use `error` param (NOT message/invalid_type_error/required_error)
z.string({ error: "Name is required" })
z.string().min(3, { error: "Too short" })

// Error map function
z.string({ error: (issue) => issue.input === undefined ? "Required" : "Invalid" })

Schema Composition

// Extend / merge
const Base = z.object({ id: z.string() });
const Extended = Base.extend({ name: z.string() });

// Pick / Omit
const Partial = Extended.pick({ name: true });

// Discriminated union (preferred over z.union for objects)
const Event = z.discriminatedUnion("type", [
  z.object({ type: z.literal("click"), x: z.number(), y: z.number() }),
  z.object({ type: z.literal("keydown"), key: z.string() }),
]);