Zod

✨ https://zod.dev ✨
TypeScript-first schema validation with static type inference

Documentation • Discord • NPM • Issues • @colinhacks • tRPC

These docs have been translated into Chinese.

Table of contents

• Introduction
  • Sponsors
  • Ecosystem
• Installation
  • Node
  • Deno
• Basic usage
• Primitives
• Literals
• Strings
• Numbers
• NaNs
• Booleans
• Dates
• Zod enums
• Native enums
• Optionals
• Nullables
• Objects
  • .shape
  • .extend
  • .merge
  • .pick/.omit
  • .partial
  • .deepPartial
  • .passthrough
  • .strict
  • .strip
  • .catchall
• Arrays
  • .element
  • .nonempty
  • .min/.max/.length
• Tuples
• Unions
• Discriminated Unions
• Records
• Maps
• Sets
• Recursive types
  • JSON type
  • Cyclical data
• Promises
• Instanceof
• Function schemas
• Preprocess
• Schema methods
  • .parse
  • .parseAsync
  • .safeParse
  • .safeParseAsync
  • .refine
  • .superRefine
  • .transform
  • .default
  • .optional
  • .nullable
  • .nullish
  • .array
  • .promise
  • .or
  • .and
• Guides and concepts
  • Type inference
  • Writing generic functions
  • Error handling
  • Error formatting
• Comparison
  • Joi
  • Yup
  • io-ts
  • Runtypes
• Changelog

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 (i.e. .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

Astro astro.build Astro is a new kind of static site builder for the modern web. Powerful developer experience meets lightweight output.	Glow Wallet glow.app Your new favorite Solana wallet.
Deletype deletype.com

Silver

Snaplet snaplet.dev	Marcato Partners marcatopartners.com	Trip
Seasoned Software seasoned.cc	Interval interval.com

Bronze

Brandon Bayer @flybayer, creator of Blitz.js	Jiří Brabec @brabeji	Alex Johansson @alexdotjs
Adaptable adaptable.io

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.

• tRPC: Build end-to-end typesafe APIs without GraphQL.
• ts-to-zod: Convert TypeScript definitions into Zod schemas.
• zod-to-ts: Generate TypeScript definitions from Zod schemas.
• @anatine/zod-openapi: Converts a Zod schema to an OpenAPI v3.x SchemaObject.
• @anatine/zod-mock: Generate mock data from a Zod schema. Powered by faker.js.
• @anatine/zod-nestjs: Helper methods for using Zod in a NestJS project.
• zod-mocking: Generate mock data from your Zod schemas.
• zod-fast-check: Generate fast-check arbitraries from Zod schemas.
• zod-endpoints: Contract-first strictly typed endpoints with Zod. OpenAPI compatible.
• express-zod-api: Build Express-based APIs with I/O schema validation and custom middlewares.
• zod-to-json-schema: Convert your Zod schemas into JSON Schemas.
• json-schema-to-zod: Convert your JSON Schemas into Zod schemas. Live demo.
• json-to-zod: Convert JSON objects into Zod schemas. Live demo.
• zod-dto: Generate Nest.js DTOs from a Zod schema.
• soly: Create CLI applications with zod.
• graphql-codegen-typescript-validation-schema: GraphQL Code Generator plugin to generate form validation schema from your GraphQL schema
• zod-prisma: Generate Zod schemas from your Prisma schema.
• fastify-type-provider-zod: Create Fastify type providers from Zod schemas
• Supervillain: Generate Zod schemas from your Go structs
• zod-to-openapi: Generate full OpenAPI (Swagger) docs from Zod, including schemas, endpoints & parameters
• prisma-zod-generator: Emit Zod schemas from your Prisma schema.
• prisma-trpc-generator: Emit fully implemented tRPC routers and their validation schemas using Zod.
• nestjs-graphql-zod: Generates NestJS GraphQL model classes from Zod schemas dynamically and provides GraphQL method decorators working with Zod schemas.

Form integrations

• react-hook-form: A first-party Zod resolver for React Hook Form
• zod-formik-adapter: A community-maintained Formik adapter for Zod
• react-zorm: Standalone <form> generation and validation for React using Zod

Installation

Requirements

• TypeScript 4.1+!

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

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

Node/NPM

To install Zod v3:

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

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}fromfrom"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 stringsconstmySchema=z.string();// parsingmySchema.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";constUser=z.object({username: z.string(),});User.parse({username: "Ludwig"});// extract the inferred typetypeUser=z.infer<typeofUser>;// { username: string }

Primitives

import{z}from"zod";// primitive valuesz.string();z.number();z.bigint();z.boolean();z.date();// empty typesz.undefined();z.null();z.void();// accepts undefined// catch-all types// allows any valuez.any();z.unknown();// never type// allows no valuesz.never();

Literals

consttuna=z.literal("tuna");consttwelve=z.literal(12);consttru=z.literal(true);// retrieve literal valuetuna.value;// "tuna"

Currently there is no support for Date or bigint 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);// trim whitespacez.string().trim();// deprecated, equivalent to .min(1)z.string().nonempty();// optional custom error messagez.string().nonempty({message: "Can't be empty"});

Check out validator.js for a bunch of other useful string validation functions.

You can customize some common error messages when creating a string schema.

constname=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"});

Numbers

You can customize certain error messages when creating a number schema.

constage=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 integerz.number().positive();// > 0z.number().nonnegative();// >= 0z.number().negative();// < 0z.number().nonpositive();// <= 0z.number().multipleOf(5);// Evenly divisible by 5. Alias .step(5)

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.

constisNaN=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.

constisActive=z.boolean({required_error: "isActive is required",invalid_type_error: "isActive must be a boolean",});

Dates

z.date() accepts a date, not a date string

z.date().safeParse(newDate());// success: truez.date().safeParse("2022-01-12T00:00:00.000Z");// success: false

To allow for dates or date strings, you can use preprocess

constdateSchema=z.preprocess((arg)=>{if(typeofarg=="string"||arginstanceofDate)returnnewDate(arg);},z.date());typeDateSchema=z.infer<typeofdateSchema>;// type DateSchema = DatedateSchema.safeParse(newDate("1/12/22"));// success: truedateSchema.safeParse("2022-01-12T00:00:00.000Z");// success: true

Zod enums

constFishEnum=z.enum(["Salmon","Tuna","Trout"]);typeFishEnum=z.infer<typeofFishEnum>;// '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.

constVALUES=["Salmon","Tuna","Trout"]asconst;constFishEnum=z.enum(VALUES);

This is not allowed, since Zod isn't able to infer the exact values of each element.

constfish=["Salmon","Tuna","Trout"];constFishEnum=z.enum(fish);

Autocompletion

To get autocompletion with a Zod enum, use the .enum property of your schema:

FishEnum.enum.Salmon;// => autocompletesFishEnum.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

enumFruits{Apple,Banana,}constFruitEnum=z.nativeEnum(Fruits);typeFruitEnum=z.infer<typeofFruitEnum>;// FruitsFruitEnum.parse(Fruits.Apple);// passesFruitEnum.parse(Fruits.Banana);// passesFruitEnum.parse(0);// passesFruitEnum.parse(1);// passesFruitEnum.parse(3);// fails

String enums

enumFruits{Apple="apple",Banana="banana",Cantaloupe,// you can mix numerical and string enums}constFruitEnum=z.nativeEnum(Fruits);typeFruitEnum=z.infer<typeofFruitEnum>;// FruitsFruitEnum.parse(Fruits.Apple);// passesFruitEnum.parse(Fruits.Cantaloupe);// passesFruitEnum.parse("apple");// passesFruitEnum.parse("banana");// passesFruitEnum.parse(0);// passesFruitEnum.parse("Cantaloupe");// fails

Const enums

The .nativeEnum() function works for as const objects as well. ⚠️as const required TypeScript 3.4+!

constFruits={Apple: "apple",Banana: "banana",Cantaloupe: 3,}asconst;constFruitEnum=z.nativeEnum(Fruits);typeFruitEnum=z.infer<typeofFruitEnum>;// "apple" | "banana" | 3FruitEnum.parse("apple");// passesFruitEnum.parse("banana");// passesFruitEnum.parse(3);// passesFruitEnum.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.

constschema=z.optional(z.string());schema.parse(undefined);// => returns undefinedtypeA=z.infer<typeofschema>;// string | undefined

For convenience, you can also call the .optional() method on an existing schema.

constuser=z.object({username: z.string().optional(),});typeC=z.infer<typeofuser>;// { username?: string | undefined };

You can extract the wrapped schema from a ZodOptional instance with .unwrap().

conststringSchema=z.string();constoptionalString=stringSchema.optional();optionalString.unwrap()===stringSchema;// true

Nullables

Similarly, you can create nullable types with z.nullable().

constnullableString=z.nullable(z.string());nullableString.parse("asdf");// => "asdf"nullableString.parse(null);// => null

Or use the .nullable() method.

constE=z.string().nullable();// equivalent to DtypeE=z.infer<typeofE>;// string | null

Extract the inner schema with .unwrap().

conststringSchema=z.string();constnullableString=stringSchema.nullable();nullableString.unwrap()===stringSchema;// true

Objects

// all properties are required by defaultconstDog=z.object({name: z.string(),age: z.number(),});// extract the inferred type like thistypeDog=z.infer<typeofDog>;// equivalent to:typeDog={name: string;age: number;};

.shape

Use .shape to access the schemas for a particular key.

Dog.shape.name;// => string schemaDog.shape.age;// => number schema

.extend

You can add additional fields to an object schema with the .extend method.

constDogWithBreed=Dog.extend({breed: z.string(),});

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

.merge

Equivalent to A.extend(B.shape).

constBaseTeacher=z.object({students: z.array(z.string())});constHasID=z.object({id: z.string()});constTeacher=BaseTeacher.merge(HasID);typeTeacher=z.infer<typeofTeacher>;// => { 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:

constRecipe=z.object({id: z.string(),name: z.string(),ingredients: z.array(z.string()),});

To only keep certain keys, use .pick .

constJustTheName=Recipe.pick({name: true});typeJustTheName=z.infer<typeofJustTheName>;// => { name: string }

To remove certain keys, use .omit .

constNoIDRecipe=Recipe.omit({id: true});typeNoIDRecipe=z.infer<typeofNoIDRecipe>;// => { 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:

constuser=z.object({email: z.string()username: z.string(),});// { email: string; username: string }

We can create a partial version:

constpartialUser=user.partial();// { email?: string | undefined; username?: string | undefined }

You can also specify which properties to make optional:

constoptionalEmail=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:

constuser=z.object({username: z.string(),location: z.object({latitude: z.number(),longitude: z.number(),}),strings: z.array(z.object({value: z.string()})),});constdeepPartialUser=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.

.passthrough

By default Zod object schemas strip out unrecognized keys during parsing.

constperson=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.

constperson=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.

constperson=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

conststringArray=z.array(z.string());// equivalentconststringArray=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().

constnonEmptyStrings=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 messageconstnonEmptyStrings=z.string().array().nonempty({message: "Can't be empty!",});

.min/.max/.length

z.string().array().min(5);// must contain 5 or more itemsz.string().array().max(5);// must contain 5 or fewer itemsz.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.

constathleteSchema=z.tuple([z.string(),// namez.number(),// jersey numberz.object({pointsScored: z.number(),}),// statistics]);typeAthlete=z.infer<typeofathleteSchema>;// type Athlete = [string, number, { pointsScored: number }]

Unions

Zod includes a built-in z.union method for composing "OR" types.

conststringOrNumber=z.union([z.string(),z.number()]);stringOrNumber.parse("foo");// passesstringOrNumber.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:

conststringOrNumber=z.string().or(z.number());

Discriminated unions

If the union consists of object schemas all identifiable by a common property, it is possible to use the z.discriminatedUnion method.

The advantage is in more efficient evaluation and more human friendly 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".

constitem=z.discriminatedUnion("type",[z.object({type: z.literal("a"),a: z.string()}),z.object({type: z.literal("b"),b: z.string()}),]).parse({type: "a",a: "abc"});

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):

constNumberCache=z.record(z.number());typeNumberCache=z.infer<typeofNumberCache>;// => { [k: string]: number }

This is particularly useful for storing or caching items by ID.

constuserStore: UserStore={};userStore["77d2586b-9e8e-4ecf-8b21-ea7e0530eadd"]={name: "Carlotta",};// passesuserStore["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):

constNoEmptyKeysSchema=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:

consttestMap: {[k: number]: string}={1: "one",};for(constkeyintestMap){console.log(`${key}: ${typeofkey}`);}// 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

conststringNumberMap=z.map(z.string(),z.number());typeStringNumberMap=z.infer<typeofstringNumberMap>;// type StringNumberMap = Map<string, number>

Sets

constnumberSet=z.set(z.number());typeNumberSet=z.infer<typeofnumberSet>;// 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 itemz.set(z.string()).min(5);// must contain 5 or more itemsz.set(z.string()).max(5);// must contain 5 or fewer itemsz.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.

constPerson=z.object({name: z.string(),});constEmployee=z.object({role: z.string(),});constEmployedPerson=z.intersection(Person,Employee);// equivalent to:constEmployedPerson=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.

consta=z.union([z.number(),z.string()]);constb=z.union([z.number(),z.boolean()]);constc=z.intersection(a,b);typec=z.infer<typeofc>;// => number

Recursive types

You can define a recursive schema in Zod, but because of a limitation of TypeScript, their type can't be statically inferred. Instead you'll need to define the type definition manually, and provide it to Zod as a "type hint".

interfaceCategory{name: string;subcategories: Category[];}// cast to z.ZodType<Category>constCategory: z.ZodType<Category>=z.lazy(()=>z.object({name: z.string(),subcategories: z.array(Category),}));Category.parse({name: "People",subcategories: [{name: "Politicians",subcategories: [{name: "Presidents",subcategories: []}],},],});// passes

Unfortunately this code is a bit duplicative, since you're declaring the types twice: once in the interface and again in the Zod definition.

JSON type

If you want to validate any JSON value, you can use the snippet below.

constliteralSchema=z.union([z.string(),z.number(),z.boolean(),z.null()]);typeLiteral=z.infer<typeofliteralSchema>;typeJson=Literal|{[key: string]: Json}|Json[];constjsonSchema: z.ZodType<Json>=z.lazy(()=>z.union([literalSchema,z.array(jsonSchema),z.record(jsonSchema)]));jsonSchema.parse(data);

Thanks to ggoodman for suggesting this.

Cyclical objects

Despite supporting recursive schemas, passing cyclical data into Zod will cause an infinite loop.

Promises

constnumberPromise=z.promise(z.number());

"Parsing" works a little differently with promise schemas. Validation happens in two parts:

1. Zod synchronously checks that the input is an instance of Promise (i.e. an object with .then and .catch methods.).
2. Zod uses .then to attach an additional validation step onto the existing Promise. You'll have to use .catch on the returned Promise to handle validation failures.

numberPromise.parse("tuna");// ZodError: Non-Promise type: stringnumberPromise.parse(Promise.resolve("tuna"));// => Promise<number>consttest=async()=>{awaitnumberPromise.parse(Promise.resolve("tuna"));// ZodError: Non-number type: stringawaitnumberPromise.parse(Promise.resolve(3.14));// => 3.14};

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.

classTest{name: string;}constTestSchema=z.instanceof(Test);constblob: any="whatever";TestSchema.parse(newTest());// passesTestSchema.parse("blob");// throws

Function schemas

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) .

constmyFunction=z.function();typemyFunction=z.infer<typeofmyFunction>;// => ()=>unknown

Define inputs and outputs.

constmyFunction=z.function().args(z.string(),z.number())// accepts an arbitrary number of arguments.returns(z.boolean());typemyFunction=z.infer<typeofmyFunction>;// => (arg0: string, arg1: number)=>boolean

Function schemas have an .implement() method which accepts a function and returns a new function that automatically validates its inputs and outputs.

consttrimmedLength=z.function().args(z.string())// accepts an arbitrary number of arguments.returns(z.number()).implement((x)=>{// TypeScript knows x is a string!returnx.trim().length;});trimmedLength("sandwich");// => 8trimmedLength(" asdf ");// => 4

If you only care about validating inputs, just don't call the .returns() method. The output type will be inferred from the implementation.

You can use the special z.void() option if your function doesn't return anything. This will let Zod properly infer the type of void-returning functions. (Void-returning functions actually return undefined.)

constmyFunction=z.function().args(z.string()).implement((arg)=>{return[arg.length];//});myFunction;// (arg: string)=>number[]

Extract the input and output schemas from a function schema.

myFunction.parameters();// => ZodTuple<[ZodString, ZodNumber]>myFunction.returnType();// => ZodBoolean

Preprocess

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().

constcastToString=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.

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.

conststringSchema=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

conststringSchema1=z.string().refine(async(val)=>val.length<20);constvalue1=awaitstringSchema.parseAsync("hello");// => helloconststringSchema2=z.string().refine(async(val)=>val.length>20);constvalue2=awaitstringSchema.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:

constresult=stringSchema.safeParse("billie");if(!result.success){// handle error then returnresult.error;}else{// do somethingresult.data;}

.safeParseAsync

Alias: .spa

An asynchronous version of safeParse.

awaitstringSchema.safeParseAsync("billie");

For convenience, this has been aliased to .spa:

awaitstringSchema.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 :

constmyString=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:

typeRefineParams={// override error messagemessage?: string;// appended to error pathpath?: (string|number)[];// params object you can use to customize message// in error mapparams?: object;};

For advanced cases, the second argument can also be a function that returns RefineParams/

z.string().refine((val)=>val.length>10,(val)=>({message: `${val} is not more than 10 characters`}));

Customize error path

constpasswordForm=z.object({password: z.string(),confirm: z.string(),}).refine((data)=>data.password===data.confirm,{message: "Passwords don't match",path: ["confirm"],// path of error}).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:

constuserId=z.string().refine(async(id)=>{// verify that ID exists in databasereturntrue;});

⚠️ 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);

.superRefine

The .refine method is actually syntactic sugar atop a more versatile (and verbose) method called superRefine. Here's an example:

constStrings=z.array(z.string()).superRefine((val,ctx)=>{if(val.length>3){ctx.addIssue({code: z.ZodIssueCode.too_big,maximum: 3,type: "array",inclusive: true,message: "Too many items 😡",});}if(val.length!==newSet(val).size){ctx.addIssue({code: z.ZodIssueCode.custom,message: `No duplicates allowed.`,});}});

You can add as many issues as you like. If ctx.addIssue is NOT called during the execution of the function, validation passes.

Normally refinements always create issues with a ZodIssueCode.custom error code, but with superRefine you can create any issue of any code. Each issue code is described in detail in the Error Handling guide: ERROR_HANDLING.md.

Abort early

By default, parsing will continue even after a refinement check fails. For instance, if you chain together multiple refinements, they will all be executed. However, it may be desirable to abort early to prevent later refinements from being executed. To achieve this, pass the fatal flag to ctx.addIssue:

constStrings=z.number().superRefine((val,ctx)=>{if(val<10){ctx.addIssue({code: z.ZodIssueCode.custom,message: "foo",fatal: true,});}}).superRefine((val,ctx)=>{if(val!==" "){ctx.addIssue({code: z.ZodIssueCode.custom,message: "bar",});}});

.transform

To transform data after parsing, use the transform method.

conststringToNumber=z.string().transform((val)=>myString.length);stringToNumber.parse("string");// => 6

⚠️ Transform functions must not throw. Make sure to use refinements before the transform or addIssue within the transform to make sure the input can be parsed by the transform.

Chaining order

Note that stringToNumber above is an instance of the ZodEffects subclass. It is NOT an instance of ZodString. If you want to use the built-in methods of ZodString (e.g. .email()) you must apply those methods before any transforms.

constemailToDomain=z.string().email().transform((val)=>val.split("@")[1]);emailToDomain.parse("colinhacks@example.com");// => example.com

Validating during transform

Similar to superRefine, transform can optionally take a ctx. This allows you to simultaneously validate and transform the value, which can be simpler than chaining refine and validate. When calling ctx.addIssue make sure to still return a value of the correct type otherwise the inferred type will include undefined.

constStrings=z.string().transform((val,ctx)=>{constparsed=parseInt(val);if(isNaN(parsed)){ctx.addIssue({code: z.ZodIssueCode.custom,message: "Not a number",});}returnparsed;});

Relationship to refinements

Transforms and refinements can be interleaved. These will be executed in the order they are declared.

z.string().transform((val)=>val.toUpperCase()).refine((val)=>val.length>15).transform((val)=>`Hello ${val}`).refine((val)=>val.indexOf("!")===-1);

Async transforms

Transforms can also be async.

constIdToUser=z.string().uuid().transform(async(id)=>{returnawaitgetUserById(id);});

⚠️ If your schema contains asynchronous transforms, you must use .parseAsync() or .safeParseAsync() to parse data. Otherwise Zod will throw an error.

.default

You can use transforms to implement the concept of "default values" in Zod.

conststringWithDefault=z.string().default("tuna");stringWithDefault.parse(undefined);// => "tuna"

Optionally, you can pass a function into .default that will be re-executed whenever a default value needs to be generated:

constnumberWithRandomDefault=z.number().default(Math.random);numberWithRandomDefault.parse(undefined);// => 0.4413456736055323numberWithRandomDefault.parse(undefined);// => 0.1871840107401901numberWithRandomDefault.parse(undefined);// => 0.7223408162401552

.optional

A convenience method that returns an optional version of a schema.

constoptionalString=z.string().optional();// string | undefined// equivalent toz.optional(z.string());

.nullable

A convenience method that returns an nullable version of a schema.

constnullableString=z.string().nullable();// string | null// equivalent toz.nullable(z.string());

.nullish

A convenience method that returns a "nullish" version of a schema. Nullish schemas will accept both undefined and null. Read more about the concept of "nullish" in the TypeScript 3.7 release notes.

constnullishString=z.string().nullish();// string | null | undefined// equivalent toz.string().optional().nullable();

.array

A convenience method that returns an array schema for the given type:

constnullableString=z.string().array();// string[]// equivalent toz.array(z.string());

.promise

A convenience method for promise types:

conststringPromise=z.string().promise();// Promise<string>// equivalent toz.promise(z.string());

.or

A convenience method for union types.

z.string().or(z.number());// string | number// equivalent toz.union([z.string(),z.number()]);

.and

A convenience method for creating intersection types.

z.object({name: z.string()}).and(z.object({age: z.number()}));// { name: string } & { age: number }// equivalent toz.intersection(z.object({name: z.string()}),z.object({age: z.number()}));

Guides and concepts

Type inference

You can extract the TypeScript type of any schema with z.infer<typeof mySchema> .

constA=z.string();typeA=z.infer<typeofA>;// stringconstu: A=12;// TypeErrorconstu: A="asdf";// compiles

What about transforms?

In reality each Zod schema internally tracks two types: an input and an output. For most schemas (e.g. z.string()) these two are the same. But once you add transforms into the mix, these two values can diverge. For instance z.string().transform(val => val.length) has an input of string and an output of number.

You can separately extract the input and output types like so:

conststringToNumber=z.string().transform((val)=>val.length);// ⚠️ Important: z.infer returns the OUTPUT type!typeinput=z.input<typeofstringToNumber>;// stringtypeoutput=z.output<typeofstringToNumber>;// number// equivalent to z.output!typeinferred=z.infer<typeofstringToNumber>;// number

Writing generic functions

When attempting to write a functions that accepts a Zod schemas as an input, it's common to try something like this:

functionmakeSchemaOptional<T>(schema: z.ZodType<T>){returnschema.optional();}

This approach has some issues. The schema variable in this function is typed as an instance of ZodType, which is an abstract class that all Zod schemas inherit from. This approach loses type information, namely which subclass the input actually is.

constarg=makeSchemaOptional(z.string());arg.unwrap();

A better approach is for the generate parameter to refer to the schema as a whole.

functionmakeSchemaOptional<Textendsz.ZodTypeAny>(schema: T){returnschema.optional();}

ZodTypeAny is just a shorthand for ZodType<any, any, any>, a type that is broad enough to match any Zod schema.

As you can see, schema is now fully and properly typed.

constarg=makeSchemaOptional(z.string());arg.unwrap();// ZodString

Constraining allowable inputs

The ZodType class has three generic parameters.

classZodType<Output=any,DefextendsZodTypeDef=ZodTypeDef,Input=Output>{ ... }

By constraining these in your generic input, you can limit what schemas are allowable as inputs to your function:

functionmakeSchemaOptional<Textendsz.ZodType<string>>(schema: T){returnschema.optional();}makeSchemaOptional(z.string());// works finemakeSchemaOptional(z.number());// Error: 'ZodNumber' is not assignable to parameter of type 'ZodType<string, ZodTypeDef, string>'

Error handling

Zod provides a subclass of Error called ZodError. ZodErrors contain an issues array containing detailed information about the validation problems.

constdata=z.object({name: z.string(),}).safeParse({name: 12});if(!data.success){data.error.issues;/* [ { "code": "invalid_type", "expected": "string", "received": "number", "path": [ "name" ], "message": "Expected string, received number" } ] */}

For detailed information about the possible error codes and how to customize error messages, check out the dedicated error handling guide: ERROR_HANDLING.md

Error formatting

You can use the .format() method to convert this error into a nested object.

constdata=z.object({name: z.string(),}).safeParse({name: 12});if(!data.success){constformatted=data.error.format();/* { name: { _errors: [ 'Expected string, received number' ] } } */formatted.name?._errors;// => ["Expected string, received number"]}

Comparison

There are a handful of other widely-used validation libraries, but all of them have certain design limitations that make for a non-ideal developer experience.

Joi

https://github.com/hapijs/joi

Doesn't support static type inference 😕

Yup

https://github.com/jquense/yup

Yup is a full-featured library that was implemented first in vanilla JS, and later rewritten in TypeScript.

• Supports casting and transforms
• All object fields are optional by default
• Missing object methods: (partial, deepPartial)

• Missing promise schemas
• Missing function schemas
• Missing union & intersection schemas

io-ts

https://github.com/gcanti/io-ts

io-ts is an excellent library by gcanti. The API of io-ts heavily inspired the design of Zod.

In our experience, io-ts prioritizes functional programming purity over developer experience in many cases. This is a valid and admirable design goal, but it makes io-ts particularly hard to integrate into an existing codebase with a more procedural or object-oriented bias. For instance, consider how to define an object with optional properties in io-ts:

import*astfrom"io-ts";constA=t.type({foo: t.string,});constB=t.partial({bar: t.number,});constC=t.intersection([A,B]);typeC=t.TypeOf<typeofC>;// returns { foo: string; bar?: number | undefined }

You must define the required and optional props in separate object validators, pass the optionals through t.partial (which marks all properties as optional), then combine them with t.intersection .

Consider the equivalent in Zod:

constC=z.object({foo: z.string(),bar: z.number().optional(),});typeC=z.infer<typeofC>;// returns { foo: string; bar?: number | undefined }

This more declarative API makes schema definitions vastly more concise.

io-ts also requires the use of gcanti's functional programming library fp-ts to parse results and handle errors. This is another fantastic resource for developers looking to keep their codebase strictly functional. But depending on fp-ts necessarily comes with a lot of intellectual overhead; a developer has to be familiar with functional programming concepts and the fp-ts nomenclature to use the library.

• Supports codecs with serialization & deserialization transforms
• Supports branded types
• Supports advanced functional programming, higher-kinded types, fp-ts compatibility
• Missing object methods: (pick, omit, partial, deepPartial, merge, extend)
• Missing nonempty arrays with proper typing ([T, ...T[]])
• Missing promise schemas
• Missing function schemas

Runtypes

https://github.com/pelotom/runtypes

Good type inference support, but limited options for object type masking (no .pick , .omit , .extend , etc.). No support for Record s (their Record is equivalent to Zod's object ). They DO support branded and readonly types, which Zod does not.

• Supports "pattern matching": computed properties that distribute over unions
• Supports readonly types
• Missing object methods: (deepPartial, merge)
• Missing nonempty arrays with proper typing ([T, ...T[]])
• Missing promise schemas
• Missing error customization

Ow

https://github.com/sindresorhus/ow

Ow is focused on function input validation. It's a library that makes it easy to express complicated assert statements, but it doesn't let you parse untyped data. They support a much wider variety of types; Zod has a nearly one-to-one mapping with TypeScript's type system, whereas ow lets you validate several highly-specific types out of the box (e.g. int32Array , see full list in their README).

If you want to validate function inputs, use function schemas in Zod! It's a much simpler approach that lets you reuse a function type declaration without repeating yourself (namely, copy-pasting a bunch of ow assertions at the beginning of every function). Also Zod lets you validate your return types as well, so you can be sure there won't be any unexpected data passed downstream.

Changelog

View the changelog at CHANGELOG.md