Data Validation with Zod

Published on February 4, 2024

Last updated on March 30, 2025

import { z } from 'zod';

export const FormSchema = z.object({
  id: z.string(),
  customerId: z.string({
      invalid_type_error: 'Please select a customer.',
  }),
  amount: z.coerce.number().gt(0, { message: 'Please enter an amount greater than $0.' }),
  status: z.enum(['pending', 'paid'], {
      invalid_type_error: 'Please select an invoice status.',
  }),
  date: z.string(),
});

What is Zod?

According to the official website, Zod is a TypeScript-first schema validation library with static type inference. It helps ensure your data matches the expected shape and types at runtime, while providing excellent TypeScript integration.

The goal is to eliminate duplication type declarations. With Zod, you declare a validator once and Zod will automatically infer the static TypeScript type. This means you don't need to maintain separate type definitions and runtime validations.

Key Features:

Zero dependencies
Works in Node.js and all modern browsers
Tiny: 8kb minified + zipped
Immutable: methods (e.g. .optional()) return a new instance
Concise, chainable interface
Functional approach: parse, don't validate
Works with plain JavaScript too! You don't need to use TypeScript
Rich error messages and customizable error handling
Extensive validation primitives out of the box

Core Features and Usage

Basic Schema Definition and Validation

import { z } from 'zod';

// Define a basic schema
const UserSchema = z.object({
  name: z.string(),
  age: z.number(),
  email: z.string().email(),
  isActive: z.boolean(),
});

// Parsing data (throws on invalid data)
try {
  const user = UserSchema.parse({
      name: 'John',
      age: 30,
      email: 'john@example.com',
      isActive: true,
  });
} catch (error) {
  console.error('Validation failed:', error);
}

// Safe parsing (returns success/error object)
const result = UserSchema.safeParse(data);
if (result.success) {
  // Type is automatically inferred
  const validatedData = result.data;
} else {
  // Handle ZodError
  console.log(result.error.errors);
}

Type Inference

Zod automatically infers TypeScript types from your schemas:

import { z } from 'zod';

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

// Extract the TypeScript type
type User = z.infer<typeof UserSchema>;
// Equivalent to:
// type User = {
  // id: string;
  // name: string;
  // age?: number;
// }

Zod offers two methods for custom validation: refine and superRefine:

// Basic refinement
const PasswordSchema = z
  .string()
  .min(8)
  .refine((password) => /[A-Z]/.test(password), {
      message: 'Password must contain at least one uppercase letter',
  });

// Complex refinement with custom error handling
const FormSchema = z
  .object({
      password: z.string(),
      confirm: z.string(),
  })
  .superRefine((data, ctx) => {
      if (data.password !== data.confirm) {
          ctx.addIssue({
              code: z.ZodIssueCode.custom,
              message: "Passwords don't match",
              path: ['confirm'], // Path of the error
          });
      }
  });

Schema Composition and Extension

Zod makes it easy to compose and extend schemas:

// Base schema
const BaseSchema = z.object({
  id: z.string().uuid(),
  createdAt: z.date(),
  updatedAt: z.date(),
});

// Extended schema
const UserSchema = BaseSchema.extend({
  username: z.string().min(3),
  email: z.string().email(),
  settings: z.object({
  theme: z.enum(['light', 'dark']),
      notifications: z.boolean(),
  }),
});

// Partial schema (all fields optional)
const PartialUserSchema = UserSchema.partial();

// Deep partial (nested fields also optional)
const DeepPartialUserSchema = UserSchema.deepPartial();

Transform and Preprocess

Zod allows you to transform data during validation:

const StringToNumberSchema = z.string().transform((str) => parseInt(str, 10));

const DateStringSchema = z.string().transform((str) => new Date(str));

const UserInputSchema = z.object({
  name: z.string().transform((str) => str.trim()),
  age: z
      .string()
      .transform((str) => parseInt(str))
      .pipe(z.number().min(18)),
});

Union Types and Discriminated Unions

// Simple union
const StringOrNumber = z.union([z.string(), z.number()]);

// Discriminated union
const Shape = z.discriminatedUnion('type', [
  z.object({ type: z.literal('circle'), radius: z.number() }),
  z.object({ type: z.literal('square'), sideLength: z.number() }),
]);

Error Handling

Zod provides detailed error information:

const schema = z.object({
  email: z.string().email(),
  age: z.number().min(18),
});

try {
  schema.parse({ email: 'invalid', age: 16 });
} catch (error) {
  if (error instanceof z.ZodError) {
      console.log(error.errors); // Array of validation issues
      console.log(error.flatten()); // Flattened error structure
  }
}

Advanced Features

Optional and Nullable Fields

const UserSchema = z.object({
  name: z.string(),
  email: z.string().email().optional(), // Field can be undefined
  phone: z.string().nullable(), // Field can be null
  age: z.number().optional().nullable(), // Field can be undefined or null
});

Array Validation

const NumberArraySchema = z.array(z.number());
const StringArraySchema = z.string().array(); // Alternative syntax
const TuppleSchema = z.tuple([z.string(), z.number()]); // Fixed-length array

Common Validation Patterns

// Empty string handling
const NonEmptyString = z.string().min(1, 'String cannot be empty');

// Custom string formats
const URLSchema = z.string().url();
const UUIDSchema = z.string().uuid();
const EmailSchema = z.string().email();

// Numeric validations
const PositiveNumber = z.number().positive();
const IntegerSchema = z.number().int();
const RangeSchema = z.number().min(0).max(100);

// Date validation
const FutureDateSchema = z.date().min(new Date());
const PastDateSchema = z.date().max(new Date());

Best Practices

Reuse Common Schemas

const BaseSchema = z.object({
  id: z.string().uuid(),
  createdAt: z.date(),
  updatedAt: z.date(),
});

const UserSchema = BaseSchema.extend({
  name: z.string(),
  email: z.string().email(),
});

Custom Error Messages

const FormSchema = z.object({
  username: z
      .string({
          required_error: 'Username is required',
          invalid_type_error: 'Username must be a string',
      })
      .min(3, 'Username must be at least 3 characters'),
});

Use Transformations for Data Cleanup

const UserInputSchema = z.object({
  email: z
      .string()
      .email()
      .transform((e) => e.toLowerCase()),
  name: z.string().transform((n) => n.trim()),
  age: z.string().transform((a) => parseInt(a, 10)),
});

Common Use Cases

API Payload Validation

const APIRequestSchema = z.object({
  query: z.string().optional(),
  page: z.number().int().positive().default(1),
  limit: z.number().int().min(1).max(100).default(10),
});

Environment Variables Validation

const EnvSchema = z.object({
  DATABASE_URL: z.string().url(),
  API_KEY: z.string().min(1),
  PORT: z.string().transform((str) => parseInt(str, 10)),
});

Configuration Validation

const ConfigSchema = z.object({
  server: z.object({
      host: z.string(),
      port: z.number(),
  }),
  database: z.object({
      url: z.string().url(),
      timeout: z.number().positive(),
  }),
  features: z.record(z.boolean()),
});

Conclusion

Zod has become a handy tool for developers dealing with form validation, especially when combined with TypeScript. Using Zod's schema declaration and validation features, developers can ensure that the data entered into forms aligns with the specified structure and adheres to predefined validation rules.

References

Zod | Documentation

GET IN TOUCH

Let's work together

I build exceptional and accessible digital experiences for the web

WRITE AN EMAIL

or reach out directly at hello@mohammadshehadeh.com