Zod is a TypeScript-first schema validation library that enables runtime type checking with static type inference. It allows developers to define schemas declaratively, parse untrusted data against those schemas, and receive strongly-typed validated results. This document covers Zod's purpose, core features, package architecture, and foundational concepts that underpin the entire system.
For installation instructions and basic usage patterns, see Installation and Setup. For detailed API documentation on specific schema types, see Schema Types and Validation.
Zod solves the problem of validating data at runtime while maintaining TypeScript type safety. When working with external data sources (APIs, user input, configuration files), standard TypeScript types provide no runtime guarantees. Zod bridges this gap by providing schemas that both validate data at runtime and infer static types for compile-time checking README.md39-60
Sources: README.md39-60
| Feature | Description |
|---|---|
| Zero Dependencies | No external runtime dependencies; entire validation system is self-contained README.md66 |
| Small Bundle Size | Core bundle is ~2kb gzipped README.md68 |
| Type Inference | Automatic TypeScript type extraction from schemas via z.infer<> README.md164-179 |
| Immutable API | Schema methods return new instances rather than mutating existing ones README.md69 |
| Universal Runtime | Works in Node.js and all modern browsers README.md67 |
| JSON Schema Integration | Built-in JSON Schema conversion README.md72 |
| Extensive Ecosystem | Thriving ecosystem including tRPC, React Hook Form, and more packages/docs/content/index.mdx137-154 |
Sources: README.md64-74 README.md164-179 packages/docs/content/index.mdx94-104 packages/docs/content/index.mdx137-154
Zod v4 follows a modular architecture where the core logic is separated from the API flavors. This design enables multiple API styles—such as the method-chaining "Classic" API and the functional "Mini" API—while maintaining a single source of truth for validation logic.
Sources: package.json74 AGENTS.md50-52 README.md44
The foundation of Zod's validation system consists of base classes that all schema types and checks extend. The core system defines $ZodType as the root for all schemas.
Sources: README.md92-96 README.md110 AGENTS.md36
Every Zod schema is an instance of a type extending $ZodType<Output, Input>. The two generic parameters represent:
Input: The type of data accepted by the schema before validation/transformation README.md186-187Output: The type of data produced by the schema after validation/transformation README.md189-191Sources: README.md181-192
Zod provides several ways to validate data. The primary methods are:
| Method | Behavior |
|---|---|
.parse(data) | Validates data and returns it; throws ZodError on failure README.md100-105 |
.parseAsync(data) | Asynchronous version of .parse for async refinements/transforms README.md107-114 |
.safeParse(data) | Returns a result object with success: true or success: false README.md144-153 |
.safeParseAsync(data) | Asynchronous version of .safeParse README.md155-162 |
Sources: README.md98-162
When validation fails, Zod produces a ZodError instance containing an array of issues README.md118-125 Each issue provides granular details like the error code, the path to the invalid data, and a human-readable message README.md126-140
Sources: README.md116-142
Zod requires TypeScript v5.5 or later packages/docs/content/index.mdx119 It is essential to enable strict mode in tsconfig.json for proper type inference packages/docs/content/index.mdx123-134
The Zod codebase is managed as a monorepo using pnpm workspaces AGENTS.md7 Development utilizes vitest for testing and biome for linting and formatting AGENTS.md9-22
Sources: package.json1-4 AGENTS.md7-22 packages/docs/content/index.mdx117-134
The current development focus is on Zod v4, which is considered stable packages/docs/content/index.mdx67 Version information is synchronized across package.json, jsr.json, and internal core version files AGENTS.md48-52
Sources: packages/docs/content/index.mdx65-69 AGENTS.md44-53
Refresh this wiki
This wiki was recently refreshed. Please wait 2 days to refresh again.