Zod Validation Patterns

Type-safe schema validation with automatic TypeScript inference.

Instructions

1. Basic Schemas

import { z } from 'zod';

// Primitives
const nameSchema = z.string().min(2).max(50);
const ageSchema = z.number().int().positive();
const emailSchema = z.string().email();
const urlSchema = z.string().url();

// Objects
const userSchema = z.object({
  id: z.string().uuid(),
  name: z.string().min(2),
  email: z.string().email(),
  age: z.number().int().min(18).optional(),
  role: z.enum(['admin', 'user', 'guest']),
  createdAt: z.coerce.date(),
});

// Infer TypeScript type
type User = z.infer<typeof userSchema>;

// Usage
const result = userSchema.safeParse(data);
if (result.success) {
  const user: User = result.data;
} else {
  console.error(result.error.format());
}

2. Complex Schemas

// Arrays
const tagsSchema = z.array(z.string()).min(1).max(10);

// Unions
const statusSchema = z.union([
  z.literal('pending'),
  z.literal('active'),
  z.literal('completed'),
]);

// Discriminated unions
const notificationSchema = z.discriminatedUnion('type', [
  z.object({ type: z.literal('email'), email: z.string().email() }),
  z.object({ type: z.literal('sms'), phone: z.string() }),
  z.object({ type: z.literal('push'), deviceId: z.string() }),
]);

// Recursive (e.g., comments with replies)
const commentSchema: z.ZodType<Comment> = z.lazy(() =>
  z.object({
    id: z.string(),
    text: z.string(),
    replies: z.array(commentSchema),
  })
);

3. Transformations

// Transform to different type
const dateStringSchema = z.string().transform((str) => new Date(str));

// Coerce types
const numberFromString = z.coerce.number(); // "123" → 123
const dateFromString = z.coerce.date();     // "2024-01-01" → Date

// Preprocess
const trimmedString = z.preprocess(
  (val) => (typeof val === 'string' ? val.trim() : val),
  z.string()
);

// Default values
const configSchema = z.object({
  port: z.number().default(3000),
  host: z.string().default('localhost'),
  debug: z.boolean().default(false),
});

4. API Response Validation

// Define response schema
const apiResponseSchema = z.object({
  success: z.boolean(),
  data: z.object({
    users: z.array(userSchema),
    total: z.number(),
    page: z.number(),
  }),
});

// Validate API response
async function fetchUsers(): Promise<User[]> {
  const response = await fetch('/api/users');
  const json = await response.json();
  
  const result = apiResponseSchema.safeParse(json);
  if (!result.success) {
    throw new Error(`Invalid API response: ${result.error.message}`);
  }
  
  return result.data.data.users;
}

5. Form Validation (React Hook Form)

import { zodResolver } from '@hookform/resolvers/zod';
import { useForm } from 'react-hook-form';

const loginSchema = z.object({
  email: z.string()
    .email('Invalid email')
    .min(1, 'Email is required'),
  password: z.string()
    .min(8, 'Password must be at least 8 characters')
    .regex(/[A-Z]/, 'Must contain uppercase')
    .regex(/[0-9]/, 'Must contain number'),
  rememberMe: z.boolean().optional(),
});

type LoginForm = z.infer<typeof loginSchema>;

function LoginForm() {
  const form = useForm<LoginForm>({
    resolver: zodResolver(loginSchema),
    defaultValues: { email: '', password: '', rememberMe: false },
  });
  
  const onSubmit = (data: LoginForm) => {
    // data is fully typed and validated
  };
}

6. Environment Variables

// env.ts
const envSchema = z.object({
  NODE_ENV: z.enum(['development', 'production', 'test']),
  DATABASE_URL: z.string().url(),
  API_KEY: z.string().min(32),
  PORT: z.coerce.number().default(3000),
  DEBUG: z.coerce.boolean().default(false),
});

// Parse with error handling
function getEnv() {
  const result = envSchema.safeParse(process.env);
  if (!result.success) {
    console.error('❌ Invalid environment variables:');
    console.error(result.error.format());
    process.exit(1);
  }
  return result.data;
}

export const env = getEnv();

// Usage
console.log(env.DATABASE_URL); // Fully typed!

7. Custom Error Messages

const userSchema = z.object({
  username: z.string({
    required_error: 'Username is required',
    invalid_type_error: 'Username must be a string',
  })
    .min(3, { message: 'Username must be at least 3 characters' })
    .max(20, { message: 'Username must be at most 20 characters' })
    .regex(/^[a-z0-9_]+$/, { message: 'Only lowercase letters, numbers, and underscores' }),
    
  email: z.string()
    .email({ message: 'Please enter a valid email address' }),
    
  age: z.number()
    .min(18, { message: 'You must be at least 18 years old' }),
});

// Get formatted errors
const result = userSchema.safeParse(data);
if (!result.success) {
  const formatted = result.error.format();
  // formatted.username?._errors
  // formatted.email?._errors
}

8. Reusable Schemas

// lib/schemas/common.ts
export const idSchema = z.string().uuid();
export const emailSchema = z.string().email().toLowerCase();
export const phoneSchema = z.string().regex(/^\+?[1-9]\d{9,14}$/);
export const urlSchema = z.string().url();
export const slugSchema = z.string().regex(/^[a-z0-9-]+$/);

// Pagination
export const paginationSchema = z.object({
  page: z.coerce.number().int().positive().default(1),
  limit: z.coerce.number().int().min(1).max(100).default(20),
});

// lib/schemas/user.ts
export const createUserSchema = z.object({
  name: z.string().min(2).max(100),
  email: emailSchema,
  password: z.string().min(8),
});

export const updateUserSchema = createUserSchema.partial();

9. Extend and Merge

// Base schema
const baseUserSchema = z.object({
  id: z.string().uuid(),
  email: z.string().email(),
});

// Extend
const fullUserSchema = baseUserSchema.extend({
  name: z.string(),
  role: z.enum(['admin', 'user']),
});

// Merge
const addressSchema = z.object({
  street: z.string(),
  city: z.string(),
});

const userWithAddressSchema = fullUserSchema.merge(addressSchema);

// Pick / Omit
const publicUserSchema = fullUserSchema.pick({ id: true, name: true });
const createUserSchema = fullUserSchema.omit({ id: true });

Best Practices

Do	Don't
✅ Use safeParse()	❌ Use parse() without try/catch
✅ Define schemas in separate files	❌ Inline schemas everywhere
✅ Use z.infer<> for types	❌ Manually define duplicate types
✅ Add custom error messages	❌ Use default cryptic errors

References

• Zod Documentation
• React Hook Form + Zod