Basic Usage

Simple Types

Create a simple string schema:

import { z } from "zod";

// Create a schema for strings
const mySchema = z.string();

// Parsing
mySchema.parse("tuna"); // => "tuna"
mySchema.parse(12); // => throws ZodError

// "Safe" parsing (doesn't throw error if validation fails)
mySchema.safeParse("tuna"); // => { success: true; data: "tuna" }
mySchema.safeParse(12); // => { success: false; error: ZodError }

Object Schemas

Create an object schema:

import { z } from "zod";

const User = z.object({
  username: z.string(),
  age: z.number(),
});

User.parse({ username: "Ludwig", age: 25 });

// Extract the inferred type
type User = z.infer<typeof User>;
// { username: string; age: number }

Error Handling

Use safeParse to handle validation errors safely:

const result = User.safeParse({ username: 123, age: "25" });

if (!result.success) {
  console.log(result.error.issues);
  // [
  //   {
  //     "code": "invalid_type",
  //     "expected": "string",
  //     "received": "number",
  //     "path": ["username"],
  //     "message": "Expected string, received number"
  //   },
  //   {
  //     "code": "invalid_type",
  //     "expected": "number",
  //     "received": "string",
  //     "path": ["age"],
  //     "message": "Expected number, received string"
  //   }
  // ]
}

Type Inference

Use z.infer to extract TypeScript types from your schemas:

const NumberSchema = z.number();
type NumberType = z.infer<typeof NumberSchema>; // number

const StringSchema = z.string();
type StringType = z.infer<typeof StringSchema>; // string

const ObjectSchema = z.object({
  name: z.string(),
  age: z.number().optional(),
});
type ObjectType = z.infer<typeof ObjectSchema>;
// { name: string; age?: number | undefined }