Basic Usage Examples

Relevant source files

This page demonstrates the fundamental patterns for using Zod: defining schemas, parsing data, and handling validation results. These examples show the most common workflows you'll use when validating data.

For installation instructions, see 1.1 Installation and Setup. For comprehensive schema API documentation, see 3 Schema Types and Validation.

Quick Start

Here's a complete example showing the basic Zod workflow:

Sources: packages/zod/README.md44-60 packages/docs/content/index.mdx78-92

Defining Schemas

Schemas define the expected structure and constraints of your data. Create schemas using factory functions from the z namespace.

Basic schema types:

Schema Type	Factory Function	Example Usage
String	`z.string()`	`z.string().min(5)`
Number	`z.number()`	`z.number().max(10)`
Boolean	`z.boolean()`	`z.boolean()`
Object	`z.object({...})`	`z.object({ id: z.string() })`
Array	`z.array(...)`	`z.array(z.string())`
Literal	`z.literal(...)`	`z.literal("hello")`
Coerce	`z.coerce.string()`	`z.coerce.number().parse("42")`

Sources: packages/docs/content/api.mdx14-25 packages/docs/content/api.mdx30-37 packages/docs/content/api.mdx117-121 packages/docs/content/api.mdx194-196 packages/zod/README.md92-96

Validation Pipeline

Validation Pipeline: From Input to Validated Output

The validation process flows through schema.parse() which calls the internal execution engine. In Zod 4, core logic is shared via the zod/v4/core package. The pipeline orchestrates type checking via inst._zod.parse() and constraint checking via the checks array. Issues are accumulated in a payload, and parsing succeeds only if no issues remain.

Sources: packages/zod/src/v4/core/schemas.ts7-12 packages/zod/src/v4/core/schemas.ts110-115 packages/zod/src/v4/core/schemas.ts218-220

Parsing Data

Using `.parse()`

The .parse() method validates input data and returns a strongly-typed deep clone of the input. If validation fails, it throws a ZodError.

Sources: packages/zod/README.md100-105 packages/zod/README.md121-142

Using `.safeParse()`

The .safeParse() method returns a result object containing either the successfully parsed data or a ZodError. The result type is a discriminated union.

Sources: packages/zod/README.md144-153 play.ts8-10

Parsing Methods Comparison

Parse vs SafeParse: Different Error Handling Strategies

Both methods perform identical validation, but differ in error handling: .parse() throws on failure while .safeParse() returns a result object. For asynchronous schemas, use .parseAsync() or .safeParseAsync().

Sources: packages/zod/README.md100-162 packages/zod/src/v4/core/schemas.ts7

Type Inference

Zod automatically infers TypeScript types from schemas using the z.infer<> utility. This keeps your TypeScript types synchronized with runtime validation.

Input vs Output Types

Schemas with transformations (.transform()) or coercion can have different input and output types:

Sources: packages/zod/README.md166-191 packages/zod/src/v4/core/schemas.ts168-173

Type System Integration

Type Inference: Bridging Compile-Time and Runtime

The z.infer<> utility extracts TypeScript types from schema definitions, ensuring type safety at compile time matches validation logic at runtime.

Sources: packages/zod/README.md166-191 packages/zod/src/v4/core/schemas.ts179-186

Async Validation

Use .parseAsync() or .safeParseAsync() when your schema contains async refinements or transforms:

Async parsing methods:

Method	Returns	Error Handling
`.parseAsync()`	`Promise<T>`	Throws `ZodError` on failure
`.safeParseAsync()`	`Promise<SafeParseResult<T>>`	Returns error in result object

Sources: packages/zod/README.md107-114 packages/zod/README.md155-162

Error Flow Diagram

Error Accumulation Flow

Validation errors are collected as issues during the parsing lifecycle. The parse() method throws a ZodError if any issues exist, while safeParse() returns them in the result object.

Sources: packages/zod/src/v4/core/schemas.ts34-38 packages/zod/src/v4/core/schemas.ts218-220 packages/zod/README.md121-142