Breaking Changes from Zod 3

typescript
1// ❌ Zod 3 (OLD)
2z.string().email();
3z.string().uuid();
4z.string().url();
5z.string().nonempty();
6z.object({ name: z.string() }).required_error('Required');
7
8// ✅ Zod 4 (NEW)
9z.email();
10z.uuid();
11z.url();
12z.string().min(1);
13z.object({ name: z.string() }, { error: 'Required' });

Basic Schemas

typescript
1import { z } from 'zod';
2
3// Primitives
4const stringSchema = z.string();
5const numberSchema = z.number();
6const booleanSchema = z.boolean();
7const dateSchema = z.date();
8
9// Top-level validators (Zod 4)
10const emailSchema = z.email();
11const uuidSchema = z.uuid();
12const urlSchema = z.url();
13
14// With constraints
15const nameSchema = z.string().min(1).max(100);
16const ageSchema = z.number().int().positive().max(150);
17const priceSchema = z.number().min(0).multipleOf(0.01);

Object Schemas

typescript
1const userSchema = z.object({
2  id: z.uuid(),
3  email: z.email({ error: 'Invalid email address' }),
4  name: z.string().min(1, { error: 'Name is required' }),
5  age: z.number().int().positive().optional(),
6  role: z.enum(['admin', 'user', 'guest']),
7  metadata: z.record(z.string(), z.unknown()).optional()
8});
9
10type User = z.infer<typeof userSchema>;
11
12// Parsing
13const user = userSchema.parse(data); // Throws on error
14const result = userSchema.safeParse(data); // Returns { success, data/error }
15
16if (result.success) {
17  console.log(result.data);
18} else {
19  console.log(result.error.issues);
20}

Arrays and Records

typescript
1// Arrays
2const tagsSchema = z.array(z.string()).min(1).max(10);
3const numbersSchema = z.array(z.number()).nonempty();
4
5// Records (objects with dynamic keys)
6const scoresSchema = z.record(z.string(), z.number());
7// { [key: string]: number }
8
9// Tuples
10const coordinatesSchema = z.tuple([z.number(), z.number()]);
11// [number, number]

Unions and Discriminated Unions

typescript
1// Simple union
2const stringOrNumber = z.union([z.string(), z.number()]);
3
4// Discriminated union (more efficient)
5const resultSchema = z.discriminatedUnion('status', [
6  z.object({ status: z.literal('success'), data: z.unknown() }),
7  z.object({ status: z.literal('error'), error: z.string() })
8]);

Transformations

typescript
1// Transform during parsing
2const lowercaseEmail = z.email().transform(email => email.toLowerCase());
3
4// Coercion (convert types)
5const numberFromString = z.coerce.number(); // "42" → 42
6const dateFromString = z.coerce.date(); // "2024-01-01" → Date
7
8// Preprocessing
9const trimmedString = z.preprocess(
10  val => (typeof val === 'string' ? val.trim() : val),
11  z.string()
12);

Refinements

typescript
1const passwordSchema = z
2  .string()
3  .min(8)
4  .refine(val => /[A-Z]/.test(val), {
5    message: 'Must contain uppercase letter'
6  })
7  .refine(val => /[0-9]/.test(val), {
8    message: 'Must contain number'
9  });
10
11// With superRefine for multiple errors
12const formSchema = z
13  .object({
14    password: z.string(),
15    confirmPassword: z.string()
16  })
17  .superRefine((data, ctx) => {
18    if (data.password !== data.confirmPassword) {
19      ctx.addIssue({
20        code: z.ZodIssueCode.custom,
21        message: "Passwords don't match",
22        path: ['confirmPassword']
23      });
24    }
25  });

Optional and Nullable

typescript
1// Optional (T | undefined)
2z.string().optional();
3
4// Nullable (T | null)
5z.string().nullable();
6
7// Both (T | null | undefined)
8z.string().nullish();
9
10// Default values
11z.string().default('unknown');
12z.number().default(() => Math.random());

Error Handling

typescript
1// Zod 4: Use 'error' param instead of 'message'
2const schema = z.object({
3  name: z.string({ error: 'Name must be a string' }),
4  email: z.email({ error: 'Invalid email format' }),
5  age: z.number().min(18, { error: 'Must be 18 or older' })
6});
7
8// Custom error map
9const customSchema = z.string({
10  error: issue => {
11    if (issue.code === 'too_small') {
12      return 'String is too short';
13    }
14    return 'Invalid string';
15  }
16});

React Hook Form Integration

typescript
1import { useForm } from "react-hook-form";
2import { zodResolver } from "@hookform/resolvers/zod";
3
4const schema = z.object({
5  email: z.email(),
6  password: z.string().min(8),
7});
8
9type FormData = z.infer<typeof schema>;
10
11function Form() {
12  const { register, handleSubmit, formState: { errors } } = useForm<FormData>({
13    resolver: zodResolver(schema),
14  });
15
16  return (
17    <form onSubmit={handleSubmit(onSubmit)}>
18      <input {...register("email")} />
19      {errors.email && <span>{errors.email.message}</span>}
20    </form>
21  );
22}

Keywords

zod, validation, schema, typescript, forms, parsing