Skip to Content
getting-started-vm39cbmBasic Usage

Last Updated: 3/12/2026

Basic Usage

This guide covers the fundamentals of using Zod: defining schemas, parsing data, and handling validation results.

Defining a Schema

Before you can validate data, you need to define a schema. Here’s a simple object schema:

import * as z from "zod";
 
const Player = z.object({
  username: z.string(),
  xp: z.number(),
});

This schema describes an object with two properties:

  • username must be a string
  • xp must be a number

Parsing Data

Use .parse() to validate an input against your schema. If the data is valid, Zod returns a strongly-typed deep clone:

const result = Player.parse({ username: "billie", xp: 100 });
// => { username: "billie", xp: 100 }
console.log(result.username); // TypeScript knows this is a string

If the data is invalid, .parse() throws a ZodError:

Player.parse({ username: 42, xp: "100" });
// => throws ZodError

Safe Parsing

To avoid try/catch blocks, use .safeParse() instead. It returns a result object that you can inspect:

const result = Player.safeParse({ username: 42, xp: "100" });
 
if (!result.success) {
  // Validation failed
  console.log(result.error);
} else {
  // Validation succeeded
  console.log(result.data.username);
}

The result type is a discriminated union , so TypeScript automatically narrows the type based on the success property.

Common Schema Types

Zod provides schema constructors for all JavaScript primitives:

z.string();    // string
z.number();    // number
z.boolean();   // boolean
z.bigint();    // bigint
z.date();      // Date
z.null();      // null
z.undefined(); // undefined

And for complex types:

z.array(z.string());              // string[]
z.object({ name: z.string() });   // { name: string }
z.union([z.string(), z.number()]); // string | number
z.record(z.string());             // Record<string, string>

Method Chaining

Zod schemas are immutable. Methods return a new schema instance, allowing you to chain validations:

const Username = z.string()
  .min(3)
  .max(20)
  .regex(/^[a-zA-Z0-9_]+$/);
 
Username.parse("billie"); // ✓
Username.parse("ab");      // ✗ too short
Username.parse("hello@world"); // ✗ invalid characters

What’s Next

InstallationError Handling