zod

TypeScript-first schema declaration and validation library with static type inference

  • zod

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
zod
18,3041513.20.22 months ago3 years agoMinified + gzip package size for zod in KB

Readme

Zod logo

Zod

✨ <a href="https://zod.dev">https://zod.dev</a> ✨
<br/>
TypeScript-first schema validation with static type inference


Zod CI status Created by Colin McDonnell License npm stars discord server


Documentation   •   Discord   •   npm   •   Issues   •   @colinhacks   •   tRPC




These docs have been translated into Chinese.

Table of contents

- Sponsors - Ecosystem - Node/npm - Deno - .shape - .keyof - .extend - .merge - .pick/.omit - .partial - .deepPartial - .passthrough - .strict - .strip - .catchall - .element - .nonempty - .min/.max/.length - JSON type - Cyclical data - .parse - .parseAsync - .safeParse - .safeParseAsync - .refine - .superRefine - .transform - .default - .catch - .optional - .nullable - .nullish - .array - .promise - .or - .and - .brand - Type inference - Writing generic functions - Error handling - Error formatting - Joi - Yup - io-ts - Runtypes

Introduction

Zod is a TypeScript-first schema declaration and validation library. I'm using the term "schema" to broadly refer to any data type, from a simple string to a complex nested object.
Zod is designed to be as developer-friendly as possible. The goal is to eliminate duplicative type declarations. With Zod, you declare a validator once and Zod will automatically infer the static TypeScript type. It's easy to compose simpler types into complex data structures.
Some other great aspects:
  • Zero dependencies
  • Works in Node.js and all modern browsers
  • Tiny: 8kb minified + zipped
  • Immutable: methods (e.g. .optional()) return a new instance
  • Concise, chainable interface
  • Functional approach: parse, don't validate
  • Works with plain JavaScript too! You don't need to use TypeScript.

Sponsors

Sponsorship at any level is appreciated and encouraged. For individual developers, consider the Cup of Coffee tier. If you built a paid product using Zod, consider one of the podium tiers.

Gold

<td align="center">
  <a href="https://astro.build/">
    <img src="https://avatars.githubusercontent.com/u/44914786?s=200&v=4" width="200px;" alt="Astro" />
  </a>
  <br />
  <b>Astro</b>
  <br />
  <a href="https://astro.build">astro.build</a>
  <br />
  <p width="200px">
    Astro is a new kind of static <br/>
    site builder for the modern web. <br/>
    Powerful developer experience meets <br/>
    lightweight output.</p>
</td>
<td align="center">
  <a href="https://glow.app/">
    <img src="https://i.imgur.com/R0R43S2.jpg" width="200px;" alt="" />
  </a>
  <br />
  <b>Glow Wallet</b>
  <br />
  <a href="https://glow.app/">glow.app</a>
  <br />
  <p width="200px">Your new favorite
    <br/>
  Solana wallet.</p>
</td>
<td align="center">
  <a href="https://deletype.com/">
    <img src="https://avatars0.githubusercontent.com/u/15068039?s=200&v=4" width="200px;" alt="Deletype logo" />
  </a>
  <br />
  <b>Deletype</b>
  <br />
  <a href="https://deletype.com">deletype.com</a>
</td>
<td align="center">
  <a href="https://proxy.com/">
    <img src="https://avatars.githubusercontent.com/u/14321439?s=200&v=4" width="200px;" alt="Proxy logo" />
  </a>
  <br />
  <b>Proxy</b>
  <br />
  <a href="https://proxy.com">proxy.com</a>
</td>

Silver

<td align="center" colspan="2">
   <a href="https://www.numeric.io">
     <img src="https://i.imgur.com/kTiLtZt.png" width="250px;" alt="Numeric logo" />
   </a>
   <br />
   <b>Numeric</b>
   <br />
   <a href="https://www.numeric.io">numeric.io</a>
 </td>
 <td align="center">
   <a href="https://snaplet.dev">
     <img src="https://avatars.githubusercontent.com/u/69029941?s=200&v=4" width="150px;" alt="Snaplet logo" />
   </a>
   <br />
   <b>Snaplet</b>
   <br />
   <a href="https://snaplet.dev">snaplet.dev</a>
 </td>
<td align="center">
   <a href="https://marcatopartners.com/">
     <img src="https://avatars.githubusercontent.com/u/84106192?s=200&v=4" width="150px;" alt="Marcato Partners" />
   </a>
   <br />
   <b>Marcato Partners</b>
   <br />
   <a href="https://marcatopartners.com/">marcatopartners.com</a>
 </td>
  <td align="center">
   <a href="https://interval.com">
     <img src="https://avatars.githubusercontent.com/u/67802063?s=200&v=4" width="150px;" alt="" />
   </a>
   <br />
   <b>Interval</b>
   <br />
   <a href="https://interval.com">interval.com</a>
 </td>
 <td align="center">
   <a href="https://seasoned.cc">
     <img src="https://avatars.githubusercontent.com/u/33913103?s=200&v=4" width="150px;" alt="" />
   </a>
   <br />
   <b>Seasoned Software</b>
   <br />
   <a href="https://seasoned.cc">seasoned.cc</a>
 </td>
<tr>
 <td align="center">
   <a href="https://www.bamboocreative.nz/">
     <img src="https://avatars.githubusercontent.com/u/41406870?v=4" width="150px;" alt="Bamboo Creative logo" />
   </a>
   <br />
   <b>Bamboo Creative</b>
   <br />
   <a href="https://www.bamboocreative.nz">bamboocreative.nz</a>
 </td>

Bronze

<td align="center">
  <a href="https://twitter.com/flybayer">
    <img src="https://avatars2.githubusercontent.com/u/8813276?s=460&u=4ff8beb9a67b173015c4b426a92d89cab960af1b&v=4" width="100px;" alt=""/>
  </a>
  <br />
  <b>Brandon Bayer</b>
  <br/>
  <a href="https://twitter.com/flybayer">@flybayer</a>,
  <span>creator of <a href="https://blitzjs.com">Blitz.js</a></span>
  <br />
</td>
<td align="center">
  <a href="https://github.com/brabeji">
    <img src="https://avatars.githubusercontent.com/u/2237954?v=4" width="100px;" alt=""/>
  </a>
  <br />
  <b>Jiří Brabec</b>
  <br/>
  <a href="https://github.com/brabeji">@brabeji</a>
  <br />
</td>
 <td align="center">
  <a href="https://twitter.com/alexdotjs">
    <img src="https://avatars.githubusercontent.com/u/459267?v=4" width="100px;" alt="" />
  </a>
  <br />
  <b>Alex Johansson</b>
  <br />
  <a href="https://twitter.com/alexdotjs">@alexdotjs</a>
</td>
<a href="https://fungible.systems/">
  <img src="https://avatars.githubusercontent.com/u/80220121?s=200&v=4" width="100px;" alt="Fungible Systems logo"/>
</a>
<br />
<b>Fungible Systems</b>
<br/>
<a href="https://fungible.systems/">fungible.systems</a>
<br />
    </td>
    <td align="center">
<a href="https://adaptable.io/">
  <img src="https://avatars.githubusercontent.com/u/60378268?s=200&v=4" width="100px;" alt=""/>
</a>
<br />
<b>Adaptable</b>
<br/>
<a href="https://adaptable.io/">adaptable.io</a>
<br />
    </td>
    <td align="center">
<a href="https://www.avanawallet.com/">
  <img src="https://avatars.githubusercontent.com/u/105452197?s=200&v=4" width="100px;" alt="Avana Wallet logo"/>
</a>
<br />
<b>Avana Wallet</b>
<br/>
<a href="https://www.avanawallet.com/">avanawallet.com</a><br/>
<span>Solana non-custodial wallet</span>
<br />
    </td>

Ecosystem

There are a growing number of tools that are built atop or support Zod natively! If you've built a tool or library on top of Zod, tell me about it on Twitter or start a Discussion. I'll add it below and tweet it out.

Resources

API libraries

  • tRPC: Build end-to-end typesafe APIs without GraphQL.
  • @anatine/zod-nestjs: Helper methods for using Zod in a NestJS project.
  • zod-endpoints: Contract-first strictly typed endpoints with Zod. OpenAPI compatible.
  • domain-functions: Decouple your business logic from your framework using composable functions. With first-class type inference from end to end powered by Zod schemas.
  • @zodios/core: A typescript API client with runtime and compile time validation backed by axios and zod.
  • express-zod-api: Build Express-based APIs with I/O schema validation and custom middlewares.

Form integrations

  • react-hook-form: A first-party Zod resolver for React Hook Form.
  • zod-validation-error: Generate user-friendly error messages from ZodErrors
  • zod-formik-adapter: A community-maintained Formik adapter for Zod.
  • react-zorm: Standalone <form> generation and validation for React using Zod.
  • zodix: Zod utilities for FormData and URLSearchParams in Remix loaders and actions.
  • formik-validator-zod: Formik-compliant validator library that simplifies using Zod with Formik.
  • zod-i18n-map: Useful for translating Zod error messages.

Zod to X

X to Zod

Mocking

Powered by Zod

  • slonik: Node.js Postgres client with strong Zod integration.
  • soly: Create CLI applications with zod.
  • zod-xlsx: A xlsx based resource validator using Zod schemas.
  • znv: Type-safe environment parsing and validation for Node.js with Zod schemas

Installation

Requirements

  • TypeScript 4.5+!
  • You must enable strict mode in your tsconfig.json. This is a best practice for all TypeScript projects.

```ts // tsconfig.json {
// ...
"compilerOptions": {
  // ...
  "strict": true
}
} ```

From npm (Node/Bun)

npm install zod       # npm
yarn add zod          # yarn
bun add zod           # bun
pnpm add zod          # pnpm

From deno.land/x (Deno)

Unlike Node, Deno relies on direct URL imports instead of a package manager like NPM. Zod is available on deno.land/x. The latest version can be imported like so:
import { z } from "https://deno.land/x/zod/mod.ts";

You can also specify a particular version:
import { z } from "https://deno.land/x/zod@v3.16.1/mod.ts";

The rest of this README assumes you are using npm and importing directly from the "zod" package.

Basic usage

Creating a simple string schema
import { z } from "zod";

// creating 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 }

Creating an object schema
import { z } from "zod";

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

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

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

Primitives

import { z } from "zod";

// primitive values
z.string();
z.number();
z.bigint();
z.boolean();
z.date();
z.symbol();

// empty types
z.undefined();
z.null();
z.void(); // accepts undefined

// catch-all types
// allows any value
z.any();
z.unknown();

// never type
// allows no values
z.never();

Literals

const tuna = z.literal("tuna");
const twelve = z.literal(12);
const twobig = z.literal(2n); // bigint literal
const tru = z.literal(true);

const terrificSymbol = Symbol("terrific");
const terrific = z.literal(terrificSymbol);

// retrieve literal value
tuna.value; // "tuna"

Currently there is no support for Date literals in Zod. If you have a use case for this feature, please file an issue.

Strings

Zod includes a handful of string-specific validations.
z.string().max(5);
z.string().min(5);
z.string().length(5);
z.string().email();
z.string().url();
z.string().uuid();
z.string().cuid();
z.string().regex(regex);
z.string().startsWith(string);
z.string().endsWith(string);
z.string().trim(); // trim whitespace
z.string().datetime(); // defaults to UTC, see below for options

Check out validator.js for a bunch of other useful string validation functions that can be used in conjunction with Refinements.

You can customize some common error messages when creating a string schema.
const name = z.string({
  required_error: "Name is required",
  invalid_type_error: "Name must be a string",
});

When using validation methods, you can pass in an additional argument to provide a custom error message.
z.string().min(5, { message: "Must be 5 or more characters long" });
z.string().max(5, { message: "Must be 5 or fewer characters long" });
z.string().length(5, { message: "Must be exactly 5 characters long" });
z.string().email({ message: "Invalid email address" });
z.string().url({ message: "Invalid url" });
z.string().uuid({ message: "Invalid UUID" });
z.string().startsWith("https://", { message: "Must provide secure URL" });
z.string().endsWith(".com", { message: "Only .com domains allowed" });
z.string().datetime({ message: "Invalid datetime string! Must be UTC." });

Coercion for primitives

Zod now provides a more convenient way to coerce primitive values.
const schema = z.coerce.string();
schema.parse("tuna"); // => "tuna"
schema.parse(12); // => "12"
schema.parse(true); // => "true"

During the parsing step, the input is passed through the String() function, which is a JavaScript built-in for coercing data into strings. Note that the returned schema is a ZodString instance so you can use all string methods.
z.coerce.string().email().min(5);

All primitive types support coercion.
z.coerce.string(); // String(input)
z.coerce.number(); // Number(input)
z.coerce.boolean(); // Boolean(input)
z.coerce.bigint(); // BigInt(input)
z.coerce.date(); // new Date(input)

Boolean coercion
Zod's boolean coercion is very simple! It passes the value into the Boolean(value) function, that's it. Any truthy value will resolve to true, any falsy value will resolve to false.
z.coerce.boolean().parse("tuna"); // => true
z.coerce.boolean().parse("true"); // => true
z.coerce.boolean().parse("false"); // => true
z.coerce.boolean().parse(1); // => true
z.coerce.boolean().parse([]); // => true

z.coerce.boolean().parse(0); // => false
z.coerce.boolean().parse(undefined); // => false
z.coerce.boolean().parse(null); // => false

Datetime validation

The z.string().datetime() method defaults to UTC validation: no timezone offsets with arbitrary sub-second decimal precision.
const datetime = z.string().datetime();

datetime.parse("2020-01-01T00:00:00Z"); // pass
datetime.parse("2020-01-01T00:00:00.123Z"); // pass
datetime.parse("2020-01-01T00:00:00.123456Z"); // pass (arbitrary precision)
datetime.parse("2020-01-01T00:00:00+02:00"); // fail (no offsets allowed)

Timezone offsets can be allowed by setting the offset option to true.
const datetime = z.string().datetime({ offset: true });

datetime.parse("2020-01-01T00:00:00+02:00"); // pass
datetime.parse("2020-01-01T00:00:00.123+02:00"); // pass (millis optional)
datetime.parse("2020-01-01T00:00:00Z"); // pass (Z still supported)

You can additionally constrain the allowable precision. By default, arbitrary sub-second precision is supported (but optional).
const datetime = z.string().datetime({ precision: 3 });

datetime.parse("2020-01-01T00:00:00.123Z"); // pass
datetime.parse("2020-01-01T00:00:00Z"); // fail
datetime.parse("2020-01-01T00:00:00.123456Z"); // fail

Numbers

You can customize certain error messages when creating a number schema.
const age = z.number({
  required_error: "Age is required",
  invalid_type_error: "Age must be a number",
});

Zod includes a handful of number-specific validations.
z.number().gt(5);
z.number().gte(5); // alias .min(5)
z.number().lt(5);
z.number().lte(5); // alias .max(5)

z.number().int(); // value must be an integer

z.number().positive(); //     > 0
z.number().nonnegative(); //  >= 0
z.number().negative(); //     < 0
z.number().nonpositive(); //  <= 0

z.number().multipleOf(5); // Evenly divisible by 5. Alias .step(5)

z.number().finite(); // value must be finite, not Infinity or -Infinity

Optionally, you can pass in a second argument to provide a custom error message.
z.number().lte(5, { message: "this👏is👏too👏big" });

NaNs

You can customize certain error messages when creating a nan schema.
const isNaN = z.nan({
  required_error: "isNaN is required",
  invalid_type_error: "isNaN must be not a number",
});

Booleans

You can customize certain error messages when creating a boolean schema.
const isActive = z.boolean({
  required_error: "isActive is required",
  invalid_type_error: "isActive must be a boolean",
});

Dates

Use z.date() to validate Date instances.
z.date().safeParse(new Date()); // success: true
z.date().safeParse("2022-01-12T00:00:00.000Z"); // success: false

You can customize certain error messages when creating a date schema.
const myDateSchema = z.date({
  required_error: "Please select a date and time",
  invalid_type_error: "That's not a date!",
});

Zod provides a handful of date-specific validations.
z.date().min(new Date("1900-01-01"), { message: "Too old" });
z.date().max(new Date(), { message: "Too young!" });

Supporting date strings
To write a schema that accepts either a Date or a date string, use z.preprocess.
const dateSchema = z.preprocess((arg) => {
  if (typeof arg == "string" || arg instanceof Date) return new Date(arg);
}, z.date());
type DateSchema = z.infer<typeof dateSchema>;
// type DateSchema = Date

dateSchema.safeParse(new Date("1/12/22")); // success: true
dateSchema.safeParse("2022-01-12T00:00:00.000Z"); // success: true

Zod enums

const FishEnum = z.enum(["Salmon", "Tuna", "Trout"]);
type FishEnum = z.infer<typeof FishEnum>;
// 'Salmon' | 'Tuna' | 'Trout'

z.enum is a Zod-native way to declare a schema with a fixed set of allowable string values. Pass the array of values directly into z.enum(). Alternatively, use as const to define your enum values as a tuple of strings. See the const assertion docs for details.
const VALUES = ["Salmon", "Tuna", "Trout"] as const;
const FishEnum = z.enum(VALUES);

This is not allowed, since Zod isn't able to infer the exact values of each element.
const fish = ["Salmon", "Tuna", "Trout"];
const FishEnum = z.enum(fish);

Autocompletion
To get autocompletion with a Zod enum, use the .enum property of your schema:
FishEnum.enum.Salmon; // => autocompletes

FishEnum.enum;
/*
=> {
  Salmon: "Salmon",
  Tuna: "Tuna",
  Trout: "Trout",
}
*/

You can also retrieve the list of options as a tuple with the .options property:
FishEnum.options; // ["Salmon", "Tuna", "Trout"]);

Native enums

Zod enums are the recommended approach to defining and validating enums. But if you need to validate against an enum from a third-party library (or you don't want to rewrite your existing enums) you can use z.nativeEnum().
Numeric enums
enum Fruits {
  Apple,
  Banana,
}

const FruitEnum = z.nativeEnum(Fruits);
type FruitEnum = z.infer<typeof FruitEnum>; // Fruits

FruitEnum.parse(Fruits.Apple); // passes
FruitEnum.parse(Fruits.Banana); // passes
FruitEnum.parse(0); // passes
FruitEnum.parse(1); // passes
FruitEnum.parse(3); // fails

String enums
enum Fruits {
  Apple = "apple",
  Banana = "banana",
  Cantaloupe, // you can mix numerical and string enums
}

const FruitEnum = z.nativeEnum(Fruits);
type FruitEnum = z.infer<typeof FruitEnum>; // Fruits

FruitEnum.parse(Fruits.Apple); // passes
FruitEnum.parse(Fruits.Cantaloupe); // passes
FruitEnum.parse("apple"); // passes
FruitEnum.parse("banana"); // passes
FruitEnum.parse(0); // passes
FruitEnum.parse("Cantaloupe"); // fails

Const enums
The .nativeEnum() function works for as const objects as well. ⚠️ as const required TypeScript 3.4+!
const Fruits = {
  Apple: "apple",
  Banana: "banana",
  Cantaloupe: 3,
} as const;

const FruitEnum = z.nativeEnum(Fruits);
type FruitEnum = z.infer<typeof FruitEnum>; // "apple" | "banana" | 3

FruitEnum.parse("apple"); // passes
FruitEnum.parse("banana"); // passes
FruitEnum.parse(3); // passes
FruitEnum.parse("Cantaloupe"); // fails

You can access the underlying object with the .enum property:
FruitEnum.enum.Apple; // "apple"

Optionals

You can make any schema optional with z.optional(). This wraps the schema in a ZodOptional instance and returns the result.
const schema = z.optional(z.string());

schema.parse(undefined); // => returns undefined
type A = z.infer<typeof schema>; // string | undefined

For convenience, you can also call the .optional() method on an existing schema.
const user = z.object({
  username: z.string().optional(),
});
type C = z.infer<typeof user>; // { username?: string | undefined };

You can extract the wrapped schema from a ZodOptional instance with .unwrap().
const stringSchema = z.string();
const optionalString = stringSchema.optional();
optionalString.unwrap() === stringSchema; // true

Nullables

Similarly, you can create nullable types with z.nullable().
const nullableString = z.nullable(z.string());
nullableString.parse("asdf"); // => "asdf"
nullableString.parse(null); // => null

Or use the .nullable() method.
const E = z.string().nullable(); // equivalent to nullableString
type E = z.infer<typeof E>; // string | null

Extract the inner schema with .unwrap().
const stringSchema = z.string();
const nullableString = stringSchema.nullable();
nullableString.unwrap() === stringSchema; // true

Objects

// all properties are required by default
const Dog = z.object({
  name: z.string(),
  age: z.number(),
});

// extract the inferred type like this
type Dog = z.infer<typeof Dog>;

// equivalent to:
type Dog = {
  name: string;
  age: number;
};

.shape

Use .shape to access the schemas for a particular key.
Dog.shape.name; // => string schema
Dog.shape.age; // => number schema

.keyof

Use .keyof to create a ZodEnum schema from the keys of an object schema.
const keySchema = Dog.keyof();
keySchema; // ZodEnum<["name", "age"]>

.extend

You can add additional fields to an object schema with the .extend method.
const DogWithBreed = Dog.extend({
  breed: z.string(),
});

You can use .extend to overwrite fields! Be careful with this power!

.merge

Equivalent to A.extend(B.shape).
const BaseTeacher = z.object({ students: z.array(z.string()) });
const HasID = z.object({ id: z.string() });

const Teacher = BaseTeacher.merge(HasID);
type Teacher = z.infer<typeof Teacher>; // => { students: string[], id: string }

If the two schemas share keys, the properties of B overrides the property of A. The returned schema also inherits the "unknownKeys" policy (strip/strict/passthrough) and the catchall schema of B.

.pick/.omit

Inspired by TypeScript's built-in Pick and Omit utility types, all Zod object schemas have .pick and .omit methods that return a modified version. Consider this Recipe schema:
const Recipe = z.object({
  id: z.string(),
  name: z.string(),
  ingredients: z.array(z.string()),
});

To only keep certain keys, use .pick .
const JustTheName = Recipe.pick({ name: true });
type JustTheName = z.infer<typeof JustTheName>;
// => { name: string }

To remove certain keys, use .omit .
const NoIDRecipe = Recipe.omit({ id: true });

type NoIDRecipe = z.infer<typeof NoIDRecipe>;
// => { name: string, ingredients: string[] }

.partial

Inspired by the built-in TypeScript utility type Partial, the .partial method makes all properties optional.
Starting from this object:
const user = z.object({
  email: z.string()
  username: z.string(),
});
// { email: string; username: string }

We can create a partial version:
const partialUser = user.partial();
// { email?: string | undefined; username?: string | undefined }

You can also specify which properties to make optional:
const optionalEmail = user.partial({
  email: true,
});
/*
{
  email?: string | undefined;
  username: string
}
*/

.deepPartial

The .partial method is shallow — it only applies one level deep. There is also a "deep" version:
const user = z.object({
  username: z.string(),
  location: z.object({
    latitude: z.number(),
    longitude: z.number(),
  }),
  strings: z.array(z.object({ value: z.string() })),
});

const deepPartialUser = user.deepPartial();

/*
{
  username?: string | undefined,
  location?: {
    latitude?: number | undefined;
    longitude?: number | undefined;
  } | undefined,
  strings?: { value?: string}[]
}
*/

Important limitation: deep partials only work as expected in hierarchies of objects, arrays, and tuples.

.required

Contrary to the .partial method, the .required method makes all properties required.
Starting from this object:
const user = z.object({
  email: z.string()
  username: z.string(),
}).partial();
// { email?: string | undefined; username?: string | undefined }

We can create a required version:
const requiredUser = user.required();
// { email: string; username: string }

You can also specify which properties to make required:
const requiredEmail = user.required({
  email: true,
});
/*
{
  email: string;
  username?: string | undefined;
}
*/

.passthrough

By default Zod object schemas strip out unrecognized keys during parsing.
const person = z.object({
  name: z.string(),
});

person.parse({
  name: "bob dylan",
  extraKey: 61,
});
// => { name: "bob dylan" }
// extraKey has been stripped

Instead, if you want to pass through unknown keys, use .passthrough() .
person.passthrough().parse({
  name: "bob dylan",
  extraKey: 61,
});
// => { name: "bob dylan", extraKey: 61 }

.strict

By default Zod object schemas strip out unrecognized keys during parsing. You can disallow unknown keys with .strict() . If there are any unknown keys in the input, Zod will throw an error.
const person = z
  .object({
    name: z.string(),
  })
  .strict();

person.parse({
  name: "bob dylan",
  extraKey: 61,
});
// => throws ZodError

.strip

You can use the .strip method to reset an object schema to the default behavior (stripping unrecognized keys).

.catchall

You can pass a "catchall" schema into an object schema. All unknown keys will be validated against it.
const person = z
  .object({
    name: z.string(),
  })
  .catchall(z.number());

person.parse({
  name: "bob dylan",
  validExtraKey: 61, // works fine
});

person.parse({
  name: "bob dylan",
  validExtraKey: false, // fails
});
// => throws ZodError

Using .catchall() obviates .passthrough() , .strip() , or .strict(). All keys are now considered "known".

Arrays

const stringArray = z.array(z.string());

// equivalent
const stringArray = z.string().array();

Be careful with the .array() method. It returns a new ZodArray instance. This means the order in which you call methods matters. For instance:
z.string().optional().array(); // (string | undefined)[]
z.string().array().optional(); // string[] | undefined

.element

Use .element to access the schema for an element of the array.
stringArray.element; // => string schema

.nonempty

If you want to ensure that an array contains at least one element, use .nonempty().
const nonEmptyStrings = z.string().array().nonempty();
// the inferred type is now
// [string, ...string[]]

nonEmptyStrings.parse([]); // throws: "Array cannot be empty"
nonEmptyStrings.parse(["Ariana Grande"]); // passes

You can optionally specify a custom error message:
// optional custom error message
const nonEmptyStrings = z.string().array().nonempty({
  message: "Can't be empty!",
});

.min/.max/.length

z.string().array().min(5); // must contain 5 or more items
z.string().array().max(5); // must contain 5 or fewer items
z.string().array().length(5); // must contain 5 items exactly

Unlike .nonempty() these methods do not change the inferred type.

Tuples

Unlike arrays, tuples have a fixed number of elements and each element can have a different type.
const athleteSchema = z.tuple([
  z.string(), // name
  z.number(), // jersey number
  z.object({
    pointsScored: z.number(),
  }), // statistics
]);

type Athlete = z.infer<typeof athleteSchema>;
// type Athlete = [string, number, { pointsScored: number }]

A variadic ("rest") argument can be added with the .rest method.
const variadicTuple = z.tuple([z.string()]).rest(z.number());
const result = variadicTuple.parse(["hello", 1, 2, 3]);
// => [string, ...number[]];

Unions

Zod includes a built-in z.union method for composing "OR" types.
const stringOrNumber = z.union([z.string(), z.number()]);

stringOrNumber.parse("foo"); // passes
stringOrNumber.parse(14); // passes

Zod will test the input against each of the "options" in order and return the first value that validates successfully.
For convenience, you can also use the .or method:
const stringOrNumber = z.string().or(z.number());

Discriminated unions

A discriminated union is a union of object schemas that all share a particular key.
type MyUnion =
  | { status: "success"; data: string }
  | { status: "failed"; error: Error };

Such unions can be represented with the z.discriminatedUnion method. This enables faster evaluation, because Zod can check the discriminator key (status in the example above) to determine which schema should be used to parse the input. This makes parsing more efficient and lets Zod report friendlier errors.
With the basic union method the input is tested against each of the provided "options", and in the case of invalidity, issues for all the "options" are shown in the zod error. On the other hand, the discriminated union allows for selecting just one of the "options", testing against it, and showing only the issues related to this "option".
const myUnion = z.discriminatedUnion("status", [
  z.object({ status: z.literal("success"), data: z.string() }),
  z.object({ status: z.literal("failed"), error: z.instanceof(Error) }),
]);

myUnion.parse({ type: "success", data: "yippie ki yay" });

Records

Record schemas are used to validate types such as { [k: string]: number }.
If you want to validate the values of an object against some schema but don't care about the keys, use z.record(valueType):
const NumberCache = z.record(z.number());

type NumberCache = z.infer<typeof NumberCache>;
// => { [k: string]: number }

This is particularly useful for storing or caching items by ID.
const userStore: UserStore = {};

userStore["77d2586b-9e8e-4ecf-8b21-ea7e0530eadd"] = {
  name: "Carlotta",
}; // passes

userStore["77d2586b-9e8e-4ecf-8b21-ea7e0530eadd"] = {
  whatever: "Ice cream sundae",
}; // TypeError

Record key type

If you want to validate both the keys and the values, use z.record(keyType, valueType):
const NoEmptyKeysSchema = z.record(z.string().min(1), z.number());
NoEmptyKeysSchema.parse({ count: 1 }); // => { 'count': 1 }
NoEmptyKeysSchema.parse({ "": 1 }); // fails

(Notice how when passing two arguments, valueType is the second argument)
A note on numerical keys
While z.record(keyType, valueType) is able to accept numerical key types and TypeScript's built-in Record type is Record<KeyType, ValueType>, it's hard to represent the TypeScript type Record<number, any> in Zod.
As it turns out, TypeScript's behavior surrounding [k: number] is a little unintuitive:
const testMap: { [k: number]: string } = {
  1: "one",
};

for (const key in testMap) {
  console.log(`${key}: ${typeof key}`);
}
// prints: `1: string`

As you can see, JavaScript automatically casts all object keys to strings under the hood. Since Zod is trying to bridge the gap between static and runtime types, it doesn't make sense to provide a way of creating a record schema with numerical keys, since there's no such thing as a numerical key in runtime JavaScript.

Maps

const stringNumberMap = z.map(z.string(), z.number());

type StringNumberMap = z.infer<typeof stringNumberMap>;
// type StringNumberMap = Map<string, number>

Sets

const numberSet = z.set(z.number());
type NumberSet = z.infer<typeof numberSet>;
// type NumberSet = Set<number>

Set schemas can be further contrainted with the following utility methods.
z.set(z.string()).nonempty(); // must contain at least one item
z.set(z.string()).min(5); // must contain 5 or more items
z.set(z.string()).max(5); // must contain 5 or fewer items
z.set(z.string()).size(5); // must contain 5 items exactly

Intersections

Intersections are useful for creating "logical AND" types. This is useful for intersecting two object types.
const Person = z.object({
  name: z.string(),
});

const Employee = z.object({
  role: z.string(),
});

const EmployedPerson = z.intersection(Person, Employee);

// equivalent to:
const EmployedPerson = Person.and(Employee);

Though in many cases, it is recommended to use A.merge(B) to merge two objects. The .merge method returns a new ZodObject instance, whereas A.and(B) returns a less useful ZodIntersection instance that lacks common object methods like pick and omit.
const a = z.union([z.number(), z.string()]);
const b = z.union([z.number(), z.boolean()]);
const c = z.intersection(a, b);

type c = z.infer<typeof c>; // => number


Instanceof

You can use z.instanceof to check that the input is an instance of a class. This is useful to validate inputs against classes that are exported from third-party libraries.
class Test {
  name: string;
}

const TestSchema = z.instanceof(Test);

const blob: any = "whatever";
TestSchema.parse(new Test()); // passes
TestSchema.parse("blob"); // throws

Functions

Zod also lets you define "function schemas". This makes it easy to validate the inputs and outputs of a function without intermixing your validation code and "business logic".
You can create a function schema with z.function(args, returnType) .
const myFunction = z.function();

type myFunction = z.infer<typeof myFunction>;
// => ()=>unknown

Define inputs and outputs.
const myFunction = z
  .function()
  .args(z.string(), z.number()) // accepts an arbitrary number of arguments
  .returns(z.boolean());

type myFunction = z.infer<typeof myFunction>;
// => (arg0: string, arg1: number)=>boolean

Preprocess

Zod now supports primitive coercion without the need for .preprocess(). See the coercion docs for more information.

Typically Zod operates under a "parse then transform" paradigm. Zod validates the input first, then passes it through a chain of transformation functions. (For more information about transforms, read the .transform docs.)
But sometimes you want to apply some transform to the input before parsing happens. A common use case: type coercion. Zod enables this with the z.preprocess().
const castToString = z.preprocess((val) => String(val), z.string());

This returns a ZodEffects instance. ZodEffects is a wrapper class that contains all logic pertaining to preprocessing, refinements, and transforms.

Custom schemas

You can create a Zod schema for any TypeScript type by using z.custom(). This is useful for creating schemas for types that are not supported by Zod out of the box, such as template string literals.
const px = z.custom<`${number}px`>((val) => /^\d+px$/.test(val));
px.parse("100px"); // pass
px.parse("100vw"); // fail

If you don't provide a validation function, Zod will allow any value. This can be dangerous!
z.custom<{ arg: string }>(); // performs no validation

Schema methods

All Zod schemas contain certain methods.

.parse

.parse(data: unknown): T
Given any Zod schema, you can call its .parse method to check data is valid. If it is, a value is returned with full type information! Otherwise, an error is thrown.
IMPORTANT: The value returned by .parse is a deep clone of the variable you passed in.

const stringSchema = z.string();

stringSchema.parse("fish"); // => returns "fish"
stringSchema.parse(12); // throws Error('Non-string type: number');

.parseAsync

.parseAsync(data:unknown): Promise<T>
If you use asynchronous refinements or transforms (more on those later), you'll need to use .parseAsync
const stringSchema1 = z.string().refine(async (val) => val.length < 20);
const value1 = await stringSchema.parseAsync("hello"); // => hello

const stringSchema2 = z.string().refine(async (val) => val.length > 20);
const value2 = await stringSchema.parseAsync("hello"); // => throws

.safeParse

.safeParse(data:unknown): { success: true; data: T; } | { success: false; error: ZodError; }
If you don't want Zod to throw errors when validation fails, use .safeParse. This method returns an object containing either the successfully parsed data or a ZodError instance containing detailed information about the validation problems.
stringSchema.safeParse(12);
// => { success: false; error: ZodError }

stringSchema.safeParse("billie");
// => { success: true; data: 'billie' }

The result is a discriminated union so you can handle errors very conveniently:
const result = stringSchema.safeParse("billie");
if (!result.success) {
  // handle error then return
  result.error;
} else {
  // do something
  result.data;
}

.safeParseAsync

Alias: .spa

An asynchronous version of safeParse.
await stringSchema.safeParseAsync("billie");

For convenience, this has been aliased to .spa:
await stringSchema.spa("billie");

.refine

.refine(validator: (data:T)=>any, params?: RefineParams)
Zod lets you provide custom validation logic via refinements. (For advanced features like creating multiple issues and customizing error codes, see .superRefine.)
Zod was designed to mirror TypeScript as closely as possible. But there are many so-called "refinement types" you may wish to check for that can't be represented in TypeScript's type system. For instance: checking that a number is an integer or that a string is a valid email address.
For example, you can define a custom validation check on any Zod schema with .refine :
const myString = z.string().refine((val) => val.length <= 255, {
  message: "String can't be more than 255 characters",
});

⚠️ Refinement functions should not throw. Instead they should return a falsy value to signal failure.

Arguments

As you can see, .refine takes two arguments.
  1. The first is the validation function. This function takes one input (of type T — the inferred type of the schema) and returns any. Any truthy value will pass validation. (Prior to zod@1.6.2 the validation function had to return a boolean.)
  2. The second argument accepts some options. You can use this to customize certain error-handling behavior:

type RefineParams = {
  // override error message
  message?: string;

  // appended to error path
  path?: (string | number)[];

  // params object you can use to customize message
  // in error map
  params?: object;
};

For advanced cases, the second argument can also be a function that returns RefineParams/
const longString = z.string().refine(
  (val) => val.length > 10,
  (val) => ({ message: `${val} is not more than 10 characters` })
);

Customize error path

const passwordForm = z
  .object({
    password: z.string(),
    confirm: z.string(),
  })
  .refine((data) => data.password === data.confirm, {
    message: "Passwords don't match",
    path: ["confirm"], // path of error
  });

passwordForm.parse({ password: "asdf", confirm: "qwer" });

Because you provided a path parameter, the resulting error will be:
ZodError {
  issues: [{
    "code": "custom",
    "path": [ "confirm" ],
    "message": "Passwords don't match"
  }]
}

Asynchronous refinements

Refinements can also be async:
const userId = z.string().refine(async (id) => {
  // verify that ID exists in database
  return true;
});

⚠️ If you use async refinements, you must use the .parseAsync method to parse data! Otherwise Zod will throw an error.

Relationship to transforms

Transforms and refinements can be interleaved:
z.string()
  .transform((val) => val.length)
  .refine((val) => val > 25);