Data Validation with Zod

Published on February 4, 2024

Last updated on June 7, 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(),
});

This example demonstrates a typical form validation schema in Zod. Let's break down each field:

id: A simple string field with no additional constraints
customerId: A string field with a custom error message when the wrong type is provided
amount: Uses z.coerce.number() to automatically convert string inputs (like from HTML forms) to numbers, then validates it's greater than 0
status: An enum that only accepts specific values ('pending' or 'paid'), perfect for dropdown selections
date: A string field for date input (you might transform this to a Date object later)

The beauty of this approach is that you get both runtime validation and TypeScript types from a single schema definition.

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);
}

Understanding Parse vs SafeParse:

parse(): Throws an error immediately when validation fails. Use this when you want exceptions to bubble up and stop execution.
safeParse(): Returns a result object with either success: true and the validated data, or success: false with error details. This is safer for user-facing applications where you want to handle errors gracefully.

The email validation automatically checks for proper email format, and all types are enforced at runtime while providing TypeScript intellisense.

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;
// }

This is one of Zod's most powerful features. You define your validation schema once, and TypeScript types are automatically generated. Notice how the optional .optional() modifier translates to age?: number in the TypeScript type. This eliminates the need to maintain separate type definitions and validation schemas, reducing code duplication and potential inconsistencies.

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
          });
      }
  });

When to Use Refine vs SuperRefine:

refine(): Best for simple, single-field validations or when you need one custom validation rule. The validation function should return a boolean.
superRefine(): More powerful for complex validations involving multiple fields, custom error paths, or when you need fine-grained control over error messages and locations.

In the password example, refine() validates a single field against a pattern. In the form example, superRefine() compares two fields and assigns the error to a specific field path, which is useful for form libraries that need to know exactly which field has 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();

Schema Composition Explained:

extend(): Adds new fields to an existing schema. Perfect for creating specialized versions of base schemas.
partial(): Makes all top-level fields optional. Useful for update operations where you might only want to change some fields.
deepPartial(): Makes all fields optional recursively, including nested object fields. Ideal for partial updates of complex nested data.

This composition approach promotes code reuse and maintains consistency across related schemas. For example, you might have a base EntitySchema with common fields like id, createdAt, updatedAt that you extend for specific entities like User, Product, etc.

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((a) => parseInt(a, 10)),
});

Benefits of Data Cleanup: Transformations handle the reality of user input - extra whitespace, inconsistent casing, and type mismatches from HTML forms. This approach ensures your data is clean and consistent before it reaches your business logic or database.

Transform Use Cases:

Transforms are powerful for data cleaning and conversion. Common scenarios include:

String cleanup: Trimming whitespace, normalizing case
Type conversion: Converting strings to numbers or dates (especially useful for form data)
Data normalization: Converting different input formats to a standard format
Chaining with pipe(): Use pipe() to chain a transform with additional validation on the transformed value

The pipe() method is particularly useful when you need to transform data and then validate the transformed result, as shown in the age example where we convert a string to a number and then ensure it meets minimum age requirements.

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() }),
]);

Understanding Union Types:

Simple unions: Use when a field can accept multiple types (like a field that accepts either a string ID or numeric ID)
Discriminated unions: Perfect for modeling different variants of data that share a common "discriminator" field. The discriminator helps Zod (and TypeScript) determine which schema to use.

Discriminated unions are especially useful for:

API responses with different shapes based on a type field
Form data that changes structure based on a selection
State management where different states have different data shapes

The discriminator field must use z.literal() to ensure exact matching of the discriminator values.

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
  }
}

Working with Zod Errors:

Zod provides rich error information that's perfect for building user-friendly forms:

error.errors: An array of all validation issues, each with details like path, message, and code
error.flatten(): Reorganizes errors into a more convenient structure for form libraries
Error paths: Each error includes the exact path to the field that failed (e.g., ['user', 'email'] for nested objects)

This detailed error information makes it easy to show specific error messages next to the relevant form fields, providing a great user experience.

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
});

Optional vs Nullable - Important Distinction:

.optional(): The field can be undefined or missing entirely from the object
.nullable(): The field must be present but can have a null value
.optional().nullable(): The field can be undefined, missing, or null

This distinction is crucial for APIs and databases:

Use .optional() for fields that might not be provided (like optional form fields)
Use .nullable() for fields that are always present but might intentionally have no value (like a nullable database column)
Combine both when a field might be missing or explicitly set to 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

Array Validation Approaches:

z.array(schema): Standard syntax for arrays of any length containing elements of the specified type
schema.array(): Alternative syntax that some developers find more readable
z.tuple([...]): For fixed-length arrays where each position has a specific type (like coordinates [x, y] or database records)

Choose tuples when the position matters and each element has a different meaning. Use regular arrays when you have a collection of similar items.

Default Values with .catch()

// .default() provides a value when the field is missing
const SchemaWithDefault = z.object({
  name: z.string(),
  role: z.string().default('user'), // Used when field is missing
});

// .catch() provides a value when validation fails
const SchemaWithCatch = z.object({
  name: z.string(),
  age: z.number().catch(0), // Used when validation fails (e.g., invalid number)
  settings: z.object({
      theme: z.enum(['light', 'dark']).catch('light'),
      notifications: z.boolean().catch(true),
  }),
});

// Example usage
const result = SchemaWithCatch.parse({
  name: 'John',
  age: 'invalid-age', // This will fail validation and use catch value
  settings: {
      theme: 'invalid-theme', // This will fail and use 'light'
      notifications: 'not-a-boolean', // This will fail and use true
  },
});

// Result will be:
// {
//   name: 'John',
//   age: 0,
//   settings: {
//     theme: 'light',
//     notifications: true
//   }
// }

When to Use .catch():

Graceful degradation: When you want your application to continue working even with invalid data
User input sanitization: For handling malformed user inputs by falling back to safe defaults
API resilience: When consuming external APIs that might return unexpected data formats
Configuration parsing: For handling corrupted or partial config files

Key Differences:

.default(value): Used when the field is missing/undefined
.catch(value): Used when the field exists but validation fails
.optional().catch(value): Combines both - handles missing fields and validation failures

This is particularly powerful for building resilient applications that can handle unexpected data gracefully rather than crashing.

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());

When to Use These Patterns:

Non-empty strings: Essential for required form fields where empty strings should be invalid
String formats: Built-in validators for common patterns save you from writing custom regex
Numeric constraints: Perfect for form inputs, age restrictions, percentage values, etc.
Date constraints: Useful for booking systems, age verification, or any time-sensitive data

These patterns handle the most common validation scenarios you'll encounter in web applications, from user registration forms to API endpoints.

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(),
});

Why This Works: Reusing common schemas ensures consistency across your application and reduces duplication. When you need to add a field like deletedAt to all entities, you only update the base schema.

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'),
});

Why Custom Messages Matter: Default error messages are technical and not user-friendly. Custom messages improve the user experience by providing clear, actionable feedback. Different message types handle different scenarios:

required_error: When the field is missing entirely
invalid_type_error: When the field has the wrong type
Validation-specific messages: For length, format, or range constraints

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),
});

Real-world Application: This schema is perfect for search or pagination endpoints. It ensures query parameters are valid, provides sensible defaults, and prevents abuse by limiting the maximum page size.

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)),
});

Real-world Application: Environment variables are strings by default, but your application needs them as proper types. This schema validates required config at startup and transforms values as needed, failing fast if configuration is invalid.

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()),
});

Real-world Application: Configuration files can have complex nested structures. This schema ensures your app config is valid before starting, preventing runtime errors from typos or missing required settings. The z.record(z.boolean()) type is perfect for feature flags.

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