Zod

if you're happy and you know it, star this repo ⭐

What is Zod
Installation
Basic usage
Defining schemas
- Primitives
- Literals
- Strings
- Numbers
- Objects
  - .shape
  - .extend
  - .merge
  - .pick/.omit
  - .partial
  - .deepPartial
  - .passthrough
  - .strict
  - .strip
  - .catchall
- Records
- Maps
- Sets
- Arrays
  - .nonempty
  - .min/.max/.length
- Unions
- Optionals
- Nullables
- Enums
  - Zod enums
  - Native enums
- Tuples
- Recursive types
  - JSON type
  - Cyclical data
- Promises
- Instanceof
- Function schemas
Base class methods (ZodType)
- .parse
- .parseAsync
- .safeParse
- .safeParseAsync
- .refine
- .transform
- .default
- .optional
- .nullable
- .array
- .or
- .and
Type inference
Errors
Comparison
- Joi
- Yup
- io-ts
- Runtypes
Changelog

Zod v3 is in alpha

New features

Transformers! But better! See the "breaking changes" section to understand the syntax changes.
You can now import Zod like import { z } from 'zod'; instead of using import * as syntax.
Added the format method to ZodError to convert the error into a strongly-typed, nested object: format method
Added the or method to ZodType (the base class for all Zod schemas) to easily create union types like z.string().or(z.number())
Added the and method to ZodType (the base class for all Zod schemas) to easily create intersection types
Added z.setErrorMap, an easier way to globally customize the error messages produced by Zod: setErrorMap
ZodOptional and ZodNullable now have a .unwrap() method for retrieving the schema they wrap

Breaking changes in v3

The minimum TypeScript version is now 4.1 (up from 3.7 for Zod 2). Several features have been rewritten to use recursive conditional types, an incredibly powerful new feature introduced in TS4.1.
Transformers syntax. Previously, creating a transformer required an input schema, an output schema, and a function to tranform between them. You created transformers like z.transform(A, B, func), where A and B are Zod schemas. This is no longer the case. Accordingly:

The old syntax (z.transformer(A, B, func)) is no longer available.

The convenience method A.transform(B, func) is no longer available.

Instead, you apply transformations by simply using the .transform() method that exists on all Zod schemas.
```
z.string().transform((val) => val.length);
```
Under the hood, all refinements and transformations are executed inside a dedicated "ZodEffects" class. Post-parsing, ZodEffects passes the data through a chain of refinements and transformations, then returns the final value. As such, you can now interleave transformations and refinements. For instance:
```
const test = z
  .string()
  .transform((val) => val.length)
  .refine((val) => val > 5, { message: "Input is too short" })
  .transform((val) => val * 2);

test.parse("12characters"); // => 24
```
Type guards (the .check() method) have been removed. Type guards interact with transformers in unintuitive ways so they were removed. Use .safeParse instead.
Object merging now behaves differently. If you merge two object schema (A.merge(B)), the fields of B will overwrite the fields of A if there are shared keys. This is how the .extend method already works. If you're looking to create an intersection of the two types, use z.intersection(A, B) or use the new .and method (A.and(B)).
There have been small internal changes to the ZodIssue type. This may impact user who have written a custom error maps. Most users will not be affected.

Migrating from v1

If you're upgrading straight to v3 from v1, you'll need to be aware of the breaking changes introduced in both v2 and v3. The v1->v2 migration guide is here.

Migrating from v2

Zod 2 is being retired and will not leave beta. This is due to some issues with it's implementation of transformers: details here. Zod 3 is currently in alpha — install it at zod@next. (Zod 2 will continue to be available with zod@beta for the time being.)

npm install zod@next
yarn add zod@next

What is Zod

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 browsers and Node.js
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.

Sponsorship

Sponsorship at any level is appreciated and encouraged. Zod is maintained by a solo developer (hi!). For individual developers, consider the Cup of Coffee tier. If you built a paid product using Zod, consider the Startup tier. You can learn more about the tiers at github.com/sponsors/colinhacks.

Installation

To install Zod v3:

npm install zod@next

TypeScript requirements

Zod 3.x requires TypeScript 4.1+
Zod 2.x requires TypeScript 3.7+
Zod 1.x requires TypeScript 3.3+

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

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

Basic usage

Creating a simple string schema

import { z } from "zod";

// creating a schema for strings
const mySchema = z.string();
mySchema.parse("tuna"); // => "tuna"
mySchema.parse(12); // => throws ZodError

Creating an object schema

import { z } from "zod";

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

User.parse({ username: string });

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

Defining schemas

Primitives

import { z } from "zod";

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

// empty types
z.undefined();
z.null();
z.void(); // accepts null or 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 tru = z.literal(true);

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().min(5);
z.string().max(5);
z.string().length(5);
z.string().email();
z.string().url();
z.string().uuid();
z.string().regex(regex);
z.string().nonempty();

Use the .nonempty method if you want the empty string ( "" ) to be considered invalid.

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

Custom error messages

Optionally, you can pass in a second 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

Zod includes a handful of number-specific validations.

z.number().min(5);
z.number().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

Optionally, you can pass in a second argument to provide a custom error message.

z.number().max(5, { message: "this👏is👏too👏big" });

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

`.extend`

You can add additional fields 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.merge(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 the merged schema take precedence.

`.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({
  username: z.string(),
});
// { username: string }

We can create a partial version:

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

`.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(),
  }),
});

const deepPartialUser = user.deepPartial();

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

Important limitation: deep partials only work as expected in direct hierarchies of object schemas. A nested object schema can't be optional, nullable, contain refinements, contain transforms, etc.

Unrecognized keys

By default Zod objects 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

`.passthrough`

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`

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

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

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

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

Optionals

You can make any schema optional with z.optional():

const schema = z.optional(z.string());

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

You can make an existing schema optional with the .optional() method:

const user = z.object({
  username: z.string().optional(),
});
type C = z.infer<typeof C>; // { username?: string | undefined };

`.unwrap`

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

Nullables

Similarly, you can create nullable types like so:

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

You can make an existing schema nullable with the nullable method:

const E = z.string().nullable(); // equivalent to D
type E = z.infer<typeof D>; // string | null

`.unwrap`

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

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

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

A note on numerical keys

You may have expected z.record() to accept two arguments, one for the keys and one for the values. After all, TypeScript's built-in Record type does: Record<KeyType, ValueType> . Otherwise, how do you 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 StringNumber = Map<string, number>

Sets

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

Enums

There are two ways to define enums in Zod.

Zod enums

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

You must pass the array of values directly into z.enum(). This does not work:

const fish = ["Salmon", "Tuna", "Trout"];
const FishEnum = z.enum(fish);

In that case, Zod isn't able to infer the individual enum elements; instead the inferred type will be string instead of 'Salmon' | 'Tuna' | 'Trout'

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

Intersections

Intersections are useful for creating "logical AND" types.

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

const stringAndNumber = z.intersection(z.string(), z.number());
type Never = z.infer<typeof stringAndNumber>; // => never

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 }]

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

interface Category {
  name: string;
  subcategories: Category[];
}

// cast to z.ZodSchema<Category>
const Category: z.ZodSchema<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.

type Literal = boolean | null | number | string;
type Json = Literal | { [key: string]: Json } | Json[];
const literalSchema = z.union([z.string(), z.number(), z.boolean(), z.null()]);
const jsonSchema: z.ZodSchema<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 an cyclical data into Zod will cause an infinite loop.

Promises

const numberPromise = z.promise(z.number());

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

Zod synchronously checks that the input is an instance of Promise (i.e. an object with .then and .catch methods.).
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: string

numberPromise.parse(Promise.resolve("tuna"));
// => Promise<number>

const test = async () => {
  await numberPromise.parse(Promise.resolve("tuna"));
  // ZodError: Non-number type: string

  await numberPromise.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.

class Test {
  name: string;
}

const TestSchema = z.instanceof(Test);

const blob: any = "whatever";
TestSchema.parse(new Test()); // passes
TestSchema.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) .

const myFunction = z.function();

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

Define inputs and output

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

Extract the input and output schemas You can extract the parameters and return type of a function schema.

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

myFunction.returnType();
// => ZodBoolean

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 function can actually return either undefined or null.)

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

const trimmedLength = z
  .function()
  .args(z.string()) // accepts an arbitrary number of arguments
  .returns(z.number())
  .implement((x) => {
    // TypeScript knows x is a string!
    return x.trim().length;
  });

trimmedLength("sandwich"); // => 8
trimmedLength(" asdf "); // => 4

If you only care about validating inputs, that's fine:

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

ZodType: methods and properties

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: In Zod 2 and Zod 1.11+, the value returned by .parse is a deep clone of the variable you passed in. This was also the case in zod@1.4 and earlier.

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 stringSchema = z.string().refine(async (val) => val.length > 20);
const value = await stringSchema.parseAsync("hello"); // => hello

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

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.

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

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

`.transform`

To transform data after parsing, use the transform method.

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

⚠️ Transformation functions must not throw. Make sure to use refinements before the transformer to make sure the input can be parsed by the transformer.

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

const emailToDomain = z
  .string()
  .email()
  .transform((val) => val.split("@")[1]);

emailToDomain.parse("colinhacks@example.com"); // => example.com

Relationship to refinements

Transforms and refinements can be interleaved:

z.string()
  .transform((val) => val.length)
  .refine((val) => val > 25);

Async transformations

Transformations can also be async.

const IdToUser = z.transformer(
  z.string().uuid(),
  UserSchema,
  (userId) => async (id) => {
    return await getUserById(id);
  }
);

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

`.default`

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

const stringWithDefault = 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:

const numberWithRandomDefault = z.number().default(Math.random);

numberWithRandomDefault.parse(undefined); // => 0.4413456736055323
numberWithRandomDefault.parse(undefined); // => 0.1871840107401901
numberWithRandomDefault.parse(undefined); // => 0.7223408162401552

`.optional`

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

const optionalString = z.string().optional(); // string | undefined

// equivalent to
z.optional(z.string());

`.nullable`

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

const nullableString = z.string().nullable(); // string | null

// equivalent to
z.nullable(z.string());

`.array`

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

const nullableString = z.string().array(); // string[]

// equivalent to
z.array(z.string());

`.or`

A convenience method for union types.

z.string().or(z.number()); // string | number

// equivalent to
z.union([z.string(), z.number()]);

`.and`

A convenience method for creating interesection types.

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

// equivalent to
z.intersection(z.string(), z.number());

Type inference

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

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

const u: A = 12; // TypeError
const u: A = "asdf"; // compiles

What about transforms?

In reality each Zod schema is actually associated with 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:

const stringToNumber = z.string().transform(val => val.length)

// ⚠️ Important: z.infer returns the OUTPUT type!
type type = z.infer<stringToNumber>; // number
type out = z.output<stringToNumber>; // number, equivalent to z.infer
type in = z.input<stringToNumber>; // string, returns input type

Errors

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

const data = 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"
      }
  ] */
}

Error formatting

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

data.error.format();
/* {
  name: { _errors: [ '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

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.

Differences

Supports for casting and transformation
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 * as t from "io-ts";

const A = t.type({
  foo: t.string,
});

const B = t.partial({
  bar: t.number,
});

const C = t.intersection([A, B]);

type C = t.TypeOf<typeof C>;
// 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:

const C = z.object({
  foo: z.string(),
  bar: z.number().optional(),
});

type C = z.infer<typeof C>;
// 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 lazy/recursive types
Missing promise schemas
Missing function schemas
Missing union & intersection schemas
Missing support for parsing cyclical data (maybe)
Missing error customization

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: (pick, omit, partial, deepPartial, merge, extend)
Missing nonempty arrays with proper typing ([T, ...T[]])
Missing lazy/recursive types
Missing promise schemas
Missing union & intersection schemas
Missing error customization
Missing record schemas (their "record" is equivalent to Zod "object")

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

Current Tags

3.21.5-alpha.0 ... alpha (a year ago)
3.23.0-beta.2 ... beta (7 months ago)
3.24.0-canary.20241107T043915 ... canary (8 days ago)
3.23.8 ... latest (6 months ago)
3.8.2-alpha.6 ... next (3 years ago)

364 Versions

3.24.0-canary.20241107T043915 ... 8 days ago
3.24.0-canary.20241016T212913 ... a month ago
3.24.0-canary.20241016T212839 ... a month ago
3.24.0-canary.20240701T200529 ... 4 months ago
3.24.0-canary.20240629T005127 ... 5 months ago
3.24.0-canary.20240523T174819 ... 6 months ago
3.23.8 ... 6 months ago
3.24.0-canary.20240508T190620 ... 6 months ago
3.23.7 ... 6 months ago
3.24.0-canary.20240507T181513 ... 6 months ago
3.23.6 ... 6 months ago
3.24.0-canary.20240502T210128 ... 6 months ago
3.23.5 ... 7 months ago
3.24.0-canary.20240429T193647 ... 7 months ago
3.24.0-canary.20240429T193306 ... 7 months ago
3.23.4 ... 7 months ago
3.24.0-canary.20240423T173108 ... 7 months ago
3.23.3 ... 7 months ago
3.23.2 ... 7 months ago
3.23.1 ... 7 months ago
3.23.0 ... 7 months ago
3.23.0-canary.20240421T221346 ... 7 months ago
3.23.0-canary.20240421T220206 ... 7 months ago
3.23.0-canary.20240420T221414 ... 7 months ago
3.23.0-beta.2 ... 7 months ago
3.22.5 ... 7 months ago
3.23.0-beta.1 ... 7 months ago
3.23.0-canary.20240418T224529 ... 7 months ago
3.23.0-canary.20240418T011308 ... 7 months ago
3.23.0-beta.0 ... 7 months ago
3.23.0-canary.20240418T003146 ... 7 months ago
3.23.0-canary.20240417T235146 ... 7 months ago
3.23.0-canary.20240417T010051 ... 7 months ago
3.23.0-canary.20240417T001802 ... 7 months ago
3.23.0-canary.20240416T233020 ... 7 months ago
3.23.0-canary.20240416T232324 ... 7 months ago
3.23.0-canary.20240416T231453 ... 7 months ago
3.23.0-canary.20240416T230918 ... 7 months ago
3.23.0-canary.20240416T222410 ... 7 months ago
3.23.0-canary.20240416T210423 ... 7 months ago
3.23.0-canary.20240416T204849 ... 7 months ago
3.23.0-canary.20240416T201354 ... 7 months ago
3.23.0-canary.20240416T195939 ... 7 months ago
3.23.0-canary.20240416T051357 ... 7 months ago
3.23.0-canary.20240414T000556 ... 7 months ago
3.23.0-canary.20240413T085656 ... 7 months ago
3.23.0-canary.20240413T011400 ... 7 months ago
3.23.0-canary.20240412T032517 ... 7 months ago
3.23.0-canary.20240412T023718 ... 7 months ago
3.23.0-canary.20240409T033359 ... 7 months ago
3.23.0-canary.20240409T032832 ... 7 months ago
3.23.0-canary.20240408T222819 ... 7 months ago
3.23.0-canary.20240407T005829 ... 7 months ago
3.23.0-canary.20240404T043228 ... 7 months ago
3.23.0-canary.20240322T225818 ... 8 months ago
3.23.0-canary.20240321T233535 ... 8 months ago
3.23.0-canary.20240321T225632 ... 8 months ago
3.23.0-canary.20240321T224206 ... 8 months ago
3.23.0-canary.20240321T200145 ... 8 months ago
3.23.0-canary.20240321T195738 ... 8 months ago
3.23.0-canary.20240319T231349 ... 8 months ago
3.23.0-canary.20240315T001949 ... 8 months ago
3.23.0-canary.20240314T051637 ... 8 months ago
3.23.0-canary.20240314T051126 ... 8 months ago
3.23.0-canary.20240222T232722 ... 9 months ago
3.23.0-canary.20240215T003902 ... 9 months ago
3.23.0-canary.20240215T003817 ... 9 months ago
3.23.0-canary.20240214T232812 ... 9 months ago
3.23.0-canary.20231004T224911 ... a year ago
3.22.4 ... a year ago
3.23.0-canary.20231004T215233 ... a year ago
3.23.0-canary.20231004T213259 ... a year ago
3.23.0-canary.20231004T210301 ... a year ago
3.23.0-canary.20231003T200509 ... a year ago
3.23.0-canary.20231003T183640 ... a year ago
3.22.3 ... a year ago
3.23.0-canary.20231003T183317 ... a year ago
3.22.2 ... a year ago
3.23.0-canary.20230815T194608 ... a year ago
3.22.1 ... a year ago
3.23.0-canary.20230815T194013 ... a year ago
3.22.0 ... a year ago
3.22.0-canary.20230814T192256 ... a year ago
3.22.0-canary.20230731T015307 ... a year ago
3.22.0-canary.20230623T202513 ... a year ago
3.22.0-canary.20230623T192520 ... a year ago
3.22.0-canary.20230623T190933 ... a year ago
3.21.5-alpha.0 ... a year ago
3.22.0-canary.20230522T011705 ... a year ago
3.22.0-canary.20230522T010750 ... a year ago
3.22.0-canary.20230521T235850 ... a year ago
3.22.0-canary.20230521T234056 ... a year ago
3.22.0-canary.20230521T230556 ... a year ago
3.22.0-canary.20230521T230122 ... a year ago
3.22.0-canary.20230521T223947 ... a year ago
3.22.0-canary.20230517T164447 ... a year ago
3.22.0-canary.20230307T060555 ... 2 years ago
3.22.0-canary.20230307T044506 ... 2 years ago
3.21.4 ... 2 years ago
3.21.3 ... 2 years ago
3.22.0-canary.20230306T212237 ... 2 years ago
3.22.0-canary.20230306T210748 ... 2 years ago
3.21.2 ... 2 years ago
3.21.1 ... 2 years ago
3.22.0-canary.20230305T095251 ... 2 years ago
3.22.0-canary.20230305T095130 ... 2 years ago
3.22.0-canary.20230305T093342 ... 2 years ago
3.22.0-canary.20230305T093225 ... 2 years ago
3.22.0-canary.20230305T082229 ... 2 years ago
3.21.0 ... 2 years ago
3.20.6 ... 2 years ago
3.20.5 ... 2 years ago
3.20.4 ... 2 years ago
3.20.4-beta.0 ... 2 years ago
3.20.3 ... 2 years ago
3.20.2 ... 2 years ago
3.20.1 ... 2 years ago
3.20.0 ... 2 years ago
3.20.0-beta.0 ... 2 years ago
3.19.1 ... 2 years ago
3.19.0 ... 2 years ago
3.19.0-beta.0 ... 2 years ago
3.18.0 ... 2 years ago
3.17.10 ... 2 years ago
3.17.9 ... 2 years ago
3.17.8 ... 2 years ago
3.17.7 ... 2 years ago
3.17.6 ... 2 years ago
3.17.5 ... 2 years ago
3.17.4 ... 2 years ago
3.17.3 ... 2 years ago
3.17.2 ... 2 years ago
3.17.0 ... 2 years ago
3.16.1 ... 2 years ago
3.16.0 ... 3 years ago
3.15.1 ... 3 years ago
3.15.0 ... 3 years ago
3.14.5 ... 3 years ago
3.14.4 ... 3 years ago
3.14.3 ... 3 years ago
3.14.2 ... 3 years ago
3.14.1 ... 3 years ago
3.14.0 ... 3 years ago
3.13.4 ... 3 years ago
3.13.3 ... 3 years ago
3.13.2 ... 3 years ago
3.13.0 ... 3 years ago
3.12.1 ... 3 years ago
3.12.0 ... 3 years ago
3.11.6 ... 3 years ago
3.11.5 ... 3 years ago
3.11.4 ... 3 years ago
3.11.3 ... 3 years ago
3.11.2 ... 3 years ago
3.11.1 ... 3 years ago
3.11.0 ... 3 years ago
3.10.3 ... 3 years ago
3.10.2 ... 3 years ago
3.10.1 ... 3 years ago
3.10.0 ... 3 years ago
3.10.0-beta.1 ... 3 years ago
3.9.8 ... 3 years ago
3.9.7 ... 3 years ago
3.9.6 ... 3 years ago
3.9.5 ... 3 years ago
3.9.4 ... 3 years ago
3.9.3 ... 3 years ago
3.9.2 ... 3 years ago
3.9.1 ... 3 years ago
3.9.0 ... 3 years ago
3.8.2 ... 3 years ago
3.8.2-alpha.6 ... 3 years ago
3.8.2-alpha.5 ... 3 years ago
3.8.2-alpha.4 ... 3 years ago
3.8.2-alpha.3 ... 3 years ago
3.8.2-alpha.2 ... 3 years ago
3.8.2-alpha.1 ... 3 years ago
3.8.1 ... 3 years ago
3.8.0 ... 3 years ago
3.7.3 ... 3 years ago
3.7.2 ... 3 years ago
3.7.1 ... 3 years ago
3.7.0 ... 3 years ago
3.6.1 ... 3 years ago
3.6.0 ... 3 years ago
3.5.4 ... 3 years ago
3.5.3 ... 3 years ago
3.5.2 ... 3 years ago
3.5.1 ... 3 years ago
3.5.0 ... 3 years ago
3.4.2 ... 3 years ago
3.4.1 ... 3 years ago
3.4.0 ... 3 years ago
3.3.4 ... 3 years ago
3.3.3 ... 3 years ago
3.3.2 ... 3 years ago
3.3.1 ... 3 years ago
3.3.0 ... 3 years ago
4.0.0-beta.1 ... 3 years ago
3.2.0 ... 3 years ago
3.2.0-beta ... 3 years ago
3.1.0 ... 3 years ago
3.0.2 ... 3 years ago
3.0.1 ... 3 years ago
3.0.0 ... 3 years ago
3.0.0-beta.4 ... 3 years ago
3.0.0-beta.3 ... 3 years ago
3.0.0-beta.2 ... 3 years ago
3.0.0-beta.1 ... 4 years ago
1.11.17 ... 4 years ago
3.0.0-alpha.40 ... 4 years ago
1.11.16 ... 4 years ago
3.0.0-alpha.39 ... 4 years ago
3.0.0-alpha.38 ... 4 years ago
3.0.0-alpha.37 ... 4 years ago
3.0.0-alpha.36 ... 4 years ago
1.11.15 ... 4 years ago
1.11.14 ... 4 years ago
3.0.0-alpha.35 ... 4 years ago
3.0.0-alpha.34 ... 4 years ago
3.0.0-alpha.33 ... 4 years ago
3.0.0-alpha.32 ... 4 years ago
3.0.0-alpha.31 ... 4 years ago
1.11.13 ... 4 years ago
3.0.0-alpha.30 ... 4 years ago
3.0.0-alpha.29 ... 4 years ago
3.0.0-alpha.28 ... 4 years ago
3.0.0-alpha.27 ... 4 years ago
3.0.0-alpha.26 ... 4 years ago
3.0.0-alpha.25 ... 4 years ago
3.0.0-alpha.24 ... 4 years ago
3.0.0-alpha.22 ... 4 years ago
3.0.0-alpha.21 ... 4 years ago
3.0.0-alpha.20 ... 4 years ago
3.0.0-alpha.19 ... 4 years ago
3.0.0-alpha.18 ... 4 years ago
3.0.0-alpha.17 ... 4 years ago
3.0.0-alpha.16 ... 4 years ago
3.0.0-alpha.15 ... 4 years ago
3.0.0-alpha.14 ... 4 years ago
3.0.0-alpha.13 ... 4 years ago
3.0.0-alpha.12 ... 4 years ago
3.0.0-alpha.11 ... 4 years ago
3.0.0-alpha.10 ... 4 years ago
3.0.0-alpha.9 ... 4 years ago
3.0.0-alpha.8 ... 4 years ago
3.0.0-alpha.7 ... 4 years ago
3.0.0-alpha.6 ... 4 years ago
1.11.12 ... 4 years ago
3.0.0-alpha.5 ... 4 years ago
2.0.0-beta.30 ... 4 years ago
3.0.0-alpha.4 ... 4 years ago
3.0.0-alpha.3 ... 4 years ago
3.0.0-alpha.2 ... 4 years ago
3.0.0-alpha.1 ... 4 years ago
2.0.0-beta.29 ... 4 years ago
2.0.0-beta.28 ... 4 years ago
2.0.0-beta.27 ... 4 years ago
2.0.0-beta.26 ... 4 years ago
2.0.0-beta.25 ... 4 years ago
1.11.11 ... 4 years ago
2.0.0-beta.24 ... 4 years ago
2.0.0-beta.23 ... 4 years ago
2.0.0-beta.22 ... 4 years ago
2.0.0-alpha.22 ... 4 years ago
2.0.0-beta.21 ... 4 years ago
2.0.0-beta.20 ... 4 years ago
2.0.0-beta.19 ... 4 years ago
2.0.0-beta.18 ... 4 years ago
2.0.0-alpha.19 ... 4 years ago
2.0.0-alpha.18 ... 4 years ago
2.0.0-beta.17 ... 4 years ago
1.11.10 ... 4 years ago
2.0.0-beta.16 ... 4 years ago
2.0.0-beta.15 ... 4 years ago
2.0.0-beta.14 ... 4 years ago
2.0.0-beta.13 ... 4 years ago
2.0.0-beta.12 ... 4 years ago
2.0.0-beta.11 ... 4 years ago
2.0.0-beta.10 ... 4 years ago
2.0.0-beta.9 ... 4 years ago
2.0.0-beta.8 ... 4 years ago
1.11.9 ... 4 years ago
2.0.0-beta.7 ... 4 years ago
2.0.0-beta.6 ... 4 years ago
2.0.1-alpha.3 ... 4 years ago
2.0.1-alpha.2 ... 4 years ago
2.0.1-alpha.1 ... 4 years ago
2.0.0-beta.5 ... 4 years ago
2.0.0-beta.4 ... 4 years ago
2.0.0-beta.3 ... 4 years ago
2.0.0-beta.2 ... 4 years ago
2.0.0-beta.1 ... 4 years ago
1.11.8 ... 4 years ago
1.11.7 ... 4 years ago
1.11.6 ... 4 years ago
1.11.5 ... 4 years ago
1.11.4 ... 4 years ago
1.11.3 ... 4 years ago
1.11.2 ... 4 years ago
1.11.1 ... 4 years ago
1.11.0 ... 4 years ago
1.10.4 ... 4 years ago
1.10.3 ... 4 years ago
1.11.0-alpha.6 ... 4 years ago
1.10.2 ... 4 years ago
1.10.2-canary ... 4 years ago
1.11.0-alpha.5 ... 4 years ago
1.10.1 ... 4 years ago
1.11.0-alpha.3 ... 4 years ago
1.11.0-alpha.2 ... 4 years ago
1.11.0-alpha.1 ... 4 years ago
1.10.0 ... 4 years ago
1.9.2 ... 4 years ago
1.9.1 ... 4 years ago
1.10.0-alpha.2 ... 4 years ago
1.10.0-alpha.1 ... 4 years ago
1.9.0 ... 4 years ago
1.8.0 ... 4 years ago
1.8.0-beta.3 ... 4 years ago
1.8.0-beta.2 ... 4 years ago
1.8.0-beta.1 ... 4 years ago
1.7.2 ... 4 years ago
2.0.0-alpha.7 ... 4 years ago
2.0.0-alpha.6 ... 4 years ago
2.0.0-alpha.5 ... 4 years ago
2.0.0-alpha.4 ... 4 years ago
2.0.0-alpha.3 ... 4 years ago
2.0.0-alpha.2 ... 4 years ago
2.0.0-alpha.1 ... 4 years ago
1.7.1 ... 4 years ago
1.7.0 ... 4 years ago
1.6.2 ... 4 years ago
1.6.1 ... 4 years ago
1.6.0 ... 5 years ago
1.5.0 ... 5 years ago
1.4.1 ... 5 years ago
1.4.0 ... 5 years ago
1.3.0 ... 5 years ago
1.2.6 ... 5 years ago
1.2.5 ... 5 years ago
1.2.4 ... 5 years ago
1.2.3 ... 5 years ago
1.2.2 ... 5 years ago
1.2.1 ... 5 years ago
1.2.0 ... 5 years ago
1.1.2 ... 5 years ago
1.1.1 ... 5 years ago
1.1.0 ... 5 years ago
1.0.15 ... 5 years ago
1.0.14 ... 5 years ago
1.0.13 ... 5 years ago
1.0.12 ... 5 years ago
1.0.11 ... 5 years ago
1.0.10 ... 5 years ago
1.0.9 ... 5 years ago
1.0.8 ... 5 years ago
1.0.7 ... 5 years ago
1.0.6 ... 5 years ago
1.0.5 ... 5 years ago
1.0.4 ... 5 years ago
1.0.2 ... 5 years ago
1.0.1 ... 5 years ago
1.0.0 ... 5 years ago

Zod

Table of contents

Zod v3 is in alpha

New features

Breaking changes in v3

Migrating from v1

Migrating from v2

What is Zod

Sponsorship

Sponsors

Installation

TypeScript requirements

Basic usage

Defining schemas

Primitives

Literals

Strings

Custom error messages

Numbers

Objects

.shape

.extend

.merge

.pick/.omit

.partial

.deepPartial

Unrecognized keys

.passthrough

.strict

.strip

.catchall

Arrays

.nonempty

.min/.max/.length

Unions

Optionals

.unwrap

Nullables

.unwrap

Records

A note on numerical keys

Maps

Sets

Enums

Zod enums

Native enums

Intersections

Tuples

Recursive types

JSON type

Cyclical objects

Promises

Instanceof

Function schemas

ZodType: methods and properties

.parse

.parseAsync

.safeParse

.safeParseAsync

.refine

Arguments

Customize error path

Asynchronous refinements

Relationship to transforms

.transform

Chaining order

Relationship to refinements

Async transformations

.default

.optional

.nullable

.array

.or

.and

Type inference

What about transforms?

Errors

Error formatting

Comparison

Joi

`.shape`

`.extend`

`.merge`

`.pick/.omit`

`.partial`

`.deepPartial`

`.passthrough`

`.strict`

`.strip`

`.catchall`

`.nonempty`

`.min/.max/.length`

`.unwrap`

`.unwrap`

`.parse`

`.parseAsync`

`.safeParse`

`.safeParseAsync`

`.refine`

`.transform`

`.default`

`.optional`

`.nullable`

`.array`

`.or`

`.and`