Zod

Overview

Zod is an open-source schema declaration and validation library designed for TypeScript and JavaScript applications. Its core functionality revolves around defining schemas that can be used to validate data at runtime and infer static types. This dual capability addresses a common challenge in type-safe development: ensuring that data conforms to expected structures not only during compilation but also when received from external sources like APIs or user inputs.

Developers use Zod to create robust validation rules for various data types, from simple strings and numbers to complex nested objects and arrays. The library's API is designed to be fluent and composable, allowing for the construction of intricate schemas with readable code. This composability supports the creation of reusable validation logic, which can be applied across different parts of an application. For instance, a schema defined for an API request body can be directly used to validate frontend form submissions and to inform the TypeScript types for those submissions, reducing manual type declarations and potential inconsistencies.

Zod's focus on type inference is a distinguishing feature. When a schema is defined, Zod can derive the corresponding TypeScript type directly from that schema. This means developers do not need to declare types separately and then build a validation schema that mirrors them. Instead, the schema acts as the single source of truth for both runtime validation and static type checking. This approach helps to prevent type-related bugs and streamline development workflows, particularly in large codebases or projects with evolving data structures. The official Zod documentation provides examples of how to define various schemas and extract their inferred types on its basic types page.

Zod is particularly well-suited for applications that require strict data integrity and type safety across their stack. This includes backend services validating incoming API requests, frontend applications validating user input in forms, and tools processing configuration files or environmental variables. Its lightweight nature and lack of external dependencies contribute to its adoption in projects where performance and bundle size are considerations. The library is maintained as a community-driven open-source project, making it accessible for developers seeking a flexible and well-documented validation solution.

Key features

• Runtime Validation: Zod validates data against defined schemas at runtime, ensuring data conforms to expected structures regardless of its origin. This is crucial for data arriving from external sources like network requests or user input.
• Type Inference: Schemas defined with Zod automatically infer corresponding static TypeScript types. This eliminates the need for manual type declaration alongside validation logic, promoting type safety and reducing repetition.
• Schema Composition: Zod's API supports combining smaller schemas into larger, more complex ones. This allows developers to build reusable validation logic and manage intricate data structures effectively.
• Custom Error Messages: Developers can define custom error messages for validation failures, providing clearer feedback to users or for debugging purposes.
• Coercion Support: Zod offers utilities for coercing input data types (e.g., converting a string to a number or a boolean), which can simplify data handling from sources like URL query parameters or form submissions.
• Asynchronous Validation: Zod schemas can include asynchronous validation logic, useful for checks that require database lookups or external API calls.
• Discriminators: The library supports creating discriminated unions, allowing for type-safe validation and inference for data that can take one of several distinct forms based on a specific property.

Pricing

Zod is a free and open-source library, distributed under the MIT License. There are no licensing costs associated with its use in commercial or personal projects.

For detailed licensing information, refer to the official Zod license information section on their documentation site.

Common integrations

• Express.js / Fastify: Zod is frequently used with Node.js web frameworks like Express.js or Fastify to validate incoming request bodies, query parameters, and route parameters. This ensures that API endpoints receive data in the expected format before processing.
• React Hook Form / Formik: In frontend applications, Zod integrates with form libraries such as React Hook Form or Formik for client-side form validation. It provides a robust way to define validation rules and display error messages to users.
• Next.js / Remix: Within full-stack frameworks like Next.js or Remix, Zod can validate data sent to API routes, server actions, or loader functions, maintaining type safety across the client-server boundary. The Remix documentation offers guidance on common validation patterns including server-side validation.
• tRPC: Zod is a foundational component of tRPC, a TypeScript-first framework for building end-to-end type-safe APIs. tRPC uses Zod schemas to infer types for API inputs, outputs, and errors, ensuring type safety from the backend to the frontend.
• Environment Variable Parsing: Developers use Zod to validate and parse environment variables, ensuring that critical configuration data is correctly formatted and present at application startup.

Alternatives

• Joi: A powerful schema description language and data validator for JavaScript, primarily focused on runtime validation.
• Yup: A JavaScript schema builder for value parsing and validation, often used for form validation in client-side applications.
• Valibot: A lightweight schema library with a focus on small bundle size, offering similar validation and type inference capabilities to Zod.

Getting started

To begin using Zod, install it via npm or yarn. This example demonstrates defining a basic user schema, validating data against it, and extracting its inferred TypeScript type.

import { z } from 'zod';

// 1. Define a Zod schema for a User
const userSchema = z.object({
  id: z.string().uuid('Invalid UUID format'),
  name: z.string().min(3, 'Name must be at least 3 characters long'),
  email: z.string().email('Invalid email address'),
  age: z.number().min(18, 'Must be at least 18 years old').optional(),
  isActive: z.boolean().default(true),
});

// 2. Infer the TypeScript type from the schema
type User = z.infer;

// 3. Example data to validate
const validUserData = {
  id: 'a1b2c3d4-e5f6-7890-1234-567890abcdef',
  name: 'Jane Doe',
  email: '[email protected]',
  age: 30,
};

const invalidUserData = {
  id: 'invalid-uuid',
  name: 'Ja',
  email: 'jane.doe@example',
  age: 15,
};

// 4. Validate data
try {
  const user1: User = userSchema.parse(validUserData);
  console.log('Valid user:', user1);
} catch (error) {
  console.error('Validation error for valid data:', error);
}

try {
  const user2: User = userSchema.parse(invalidUserData);
  console.log('Invalid user (this should not be logged):', user2);
} catch (error) {
  console.error('Validation error for invalid data:', JSON.parse(error.message));
}

// 5. Example with default value
const newUserWithDefaults = userSchema.parse({
  id: 'f9e8d7c6-b5a4-3210-fedc-ba9876543210',
  name: 'John Smith',
  email: '[email protected]',
});
console.log('New user with defaults:', newUserWithDefaults);
// Expected output: New user with defaults: { id: ..., name: 'John Smith', email: '[email protected]', isActive: true }

This snippet illustrates how to define an object schema with various types and validation rules, infer a TypeScript type, and use the parse method for synchronous validation. Errors are caught and logged, showcasing Zod's error reporting capabilities. More advanced usage, including asynchronous validations and custom refinements, can be found in the Zod documentation.