Zod Schema Validation Patterns

Zod provides TypeScript-first schema validation. Here's how to use it for forms, APIs, and data transformation.

Basic Schemas#

import { z } from 'zod';

// Primitive types
const stringSchema = z.string();
const numberSchema = z.number();
const booleanSchema = z.boolean();
const dateSchema = z.date();

// With constraints
const emailSchema = z.string().email('Invalid email address');
const ageSchema = z.number().min(0).max(120);
const urlSchema = z.string().url();
const uuidSchema = z.string().uuid();

// Optional and nullable
const optionalString = z.string().optional(); // string | undefined
const nullableString = z.string().nullable(); // string | null
const nullishString = z.string().nullish();   // string | null | undefined

// Default values
const statusSchema = z.string().default('pending');

// Literals and enums
const roleSchema = z.enum(['admin', 'user', 'guest']);
const statusLiteral = z.literal('active');

// Parse and validate
const result = emailSchema.parse('user@example.com'); // Returns string or throws
const safeResult = emailSchema.safeParse('invalid'); // Returns { success, data/error }

Object Schemas#

// Object schema
const userSchema = z.object({
  id: z.string().uuid(),
  email: z.string().email(),
  name: z.string().min(2).max(100),
  age: z.number().int().positive().optional(),
  role: z.enum(['admin', 'user']),
  createdAt: z.date(),
});

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

// Partial - all fields optional
const partialUserSchema = userSchema.partial();

// Pick specific fields
const userCredentials = userSchema.pick({ email: true, name: true });

// Omit fields
const userWithoutId = userSchema.omit({ id: true });

// Extend schema
const adminUserSchema = userSchema.extend({
  permissions: z.array(z.string()),
});

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

const userWithAddressSchema = userSchema.merge(addressSchema);

// Strict and passthrough
const strictSchema = z.object({ name: z.string() }).strict(); // Fails on extra keys
const passthroughSchema = z.object({ name: z.string() }).passthrough(); // Allows extra keys

Array and Tuple Schemas#

// Arrays
const tagsSchema = z.array(z.string());
const itemsSchema = z.array(z.object({
  id: z.string(),
  quantity: z.number().positive(),
}));

// Array constraints
const limitedArray = z.array(z.string()).min(1).max(10);
const nonEmptyArray = z.array(z.string()).nonempty();

// Tuples
const coordinatesSchema = z.tuple([z.number(), z.number()]);
const mixedTupleSchema = z.tuple([z.string(), z.number(), z.boolean()]);

// Rest elements
const argsSchema = z.tuple([z.string()]).rest(z.number());
// [string, ...number[]]

Union and Discriminated Union#

// Union types
const stringOrNumber = z.union([z.string(), z.number()]);
// Shorthand
const stringOrNumberShort = z.string().or(z.number());

// Discriminated union (more efficient)
const eventSchema = z.discriminatedUnion('type', [
  z.object({
    type: z.literal('click'),
    x: z.number(),
    y: z.number(),
  }),
  z.object({
    type: z.literal('keypress'),
    key: z.string(),
  }),
  z.object({
    type: z.literal('scroll'),
    direction: z.enum(['up', 'down']),
  }),
]);

type Event = z.infer<typeof eventSchema>;

// API response pattern
const apiResponseSchema = z.discriminatedUnion('status', [
  z.object({
    status: z.literal('success'),
    data: z.unknown(),
  }),
  z.object({
    status: z.literal('error'),
    error: z.string(),
    code: z.number(),
  }),
]);

Transformations#

// Transform during parsing
const lowercaseEmail = z.string().email().transform((val) => val.toLowerCase());

// Parse and transform
const numberFromString = z.string().transform((val) => parseInt(val, 10));

// Coercion (built-in transforms)
const coercedNumber = z.coerce.number(); // Converts to number
const coercedString = z.coerce.string(); // Converts to string
const coercedDate = z.coerce.date();     // Converts to Date

// Complex transformation
const userInputSchema = z.object({
  email: z.string().email().transform((s) => s.toLowerCase().trim()),
  birthDate: z.string().transform((s) => new Date(s)),
  tags: z.string().transform((s) => s.split(',').map((t) => t.trim())),
});

// Pre-process input before validation
const preprocessedSchema = z.preprocess(
  (val) => (typeof val === 'string' ? JSON.parse(val) : val),
  z.object({ name: z.string() })
);

// Refine with custom validation
const passwordSchema = z.string()
  .min(8, 'Password must be at least 8 characters')
  .refine((val) => /[A-Z]/.test(val), 'Must contain uppercase')
  .refine((val) => /[0-9]/.test(val), 'Must contain number');

Custom Validation with Refine#

// Simple refine
const evenNumber = z.number().refine((n) => n % 2 === 0, {
  message: 'Must be an even number',
});

// Async refine
const uniqueEmail = z.string().email().refine(
  async (email) => {
    const exists = await checkEmailExists(email);
    return !exists;
  },
  { message: 'Email already in use' }
);

// Super refine for complex validation
const formSchema = z.object({
  password: z.string().min(8),
  confirmPassword: z.string(),
}).superRefine((data, ctx) => {
  if (data.password !== data.confirmPassword) {
    ctx.addIssue({
      code: z.ZodIssueCode.custom,
      message: 'Passwords do not match',
      path: ['confirmPassword'],
    });
  }
});

// Conditional validation
const conditionalSchema = z.object({
  hasDiscount: z.boolean(),
  discountCode: z.string().optional(),
}).refine(
  (data) => {
    if (data.hasDiscount && !data.discountCode) {
      return false;
    }
    return true;
  },
  {
    message: 'Discount code is required when hasDiscount is true',
    path: ['discountCode'],
  }
);

React Hook Form Integration#

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

const signupSchema = z.object({
  email: z.string().email('Invalid email'),
  password: z.string().min(8, 'Password must be at least 8 characters'),
  confirmPassword: z.string(),
  acceptTerms: z.literal(true, {
    errorMap: () => ({ message: 'You must accept the terms' }),
  }),
}).refine((data) => data.password === data.confirmPassword, {
  message: 'Passwords do not match',
  path: ['confirmPassword'],
});

type SignupForm = z.infer<typeof signupSchema>;

function SignupForm() {
  const {
    register,
    handleSubmit,
    formState: { errors },
  } = useForm<SignupForm>({
    resolver: zodResolver(signupSchema),
  });

  const onSubmit = (data: SignupForm) => {
    console.log(data);
  };

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <input {...register('email')} type="email" />
      {errors.email && <span>{errors.email.message}</span>}

      <input {...register('password')} type="password" />
      {errors.password && <span>{errors.password.message}</span>}

      <input {...register('confirmPassword')} type="password" />
      {errors.confirmPassword && <span>{errors.confirmPassword.message}</span>}

      <input {...register('acceptTerms')} type="checkbox" />
      {errors.acceptTerms && <span>{errors.acceptTerms.message}</span>}

      <button type="submit">Sign Up</button>
    </form>
  );
}

API Validation#

// Express middleware
import { Request, Response, NextFunction } from 'express';

function validate<T>(schema: z.ZodType<T>) {
  return (req: Request, res: Response, next: NextFunction) => {
    const result = schema.safeParse(req.body);

    if (!result.success) {
      return res.status(400).json({
        error: 'Validation failed',
        issues: result.error.issues,
      });
    }

    req.body = result.data;
    next();
  };
}

const createUserSchema = z.object({
  email: z.string().email(),
  name: z.string().min(2),
  role: z.enum(['admin', 'user']).default('user'),
});

app.post('/users', validate(createUserSchema), (req, res) => {
  // req.body is typed and validated
  const user = req.body;
  // ...
});

// tRPC integration
import { initTRPC } from '@trpc/server';

const t = initTRPC.create();

const appRouter = t.router({
  createUser: t.procedure
    .input(createUserSchema)
    .mutation(({ input }) => {
      // input is typed
      return createUser(input);
    }),
});

Best Practices#

Schemas:
✓ Define schemas close to usage
✓ Reuse common schemas
✓ Use discriminated unions for tagged types
✓ Export inferred types

Validation:
✓ Provide helpful error messages
✓ Use coercion for external input
✓ Validate at system boundaries
✓ Handle async validation carefully

Performance:
✓ Parse once, use types after
✓ Avoid excessive refinements
✓ Cache compiled schemas
✓ Use strict mode appropriately

Zod bridges runtime validation and TypeScript types. Use object schemas for structured data, discriminated unions for tagged types, and transformations for data cleaning. Integration with React Hook Form and tRPC makes Zod essential for full-stack TypeScript applications.