TypeScript-first schema declaration and validation library with static type inference
Zod is a TypeScript-first schema declaration and validation library. It allows developers to create complex schemas for data validation with a simple and intuitive API. Zod schemas are composable and can be used to validate data at the edge of your application, ensuring that you're working with well-structured and type-safe data.
Basic Type Validation
Validates that the input is a string.
{"const schema = zod.string(); try { schema.parse('hello world'); } catch (e) { console.error(e); }"}Object Schema Validation
Validates that the input is an object with specific properties of certain types.
{"const userSchema = zod.object({ name: zod.string(), age: zod.number(), email: zod.string().email() }); try { userSchema.parse({ name: 'John', age: 30, email: 'john@example.com' }); } catch (e) { console.error(e); }"}Array Validation
Validates that the input is an array of strings.
{"const stringArraySchema = zod.array(zod.string()); try { stringArraySchema.parse(['apple', 'banana']); } catch (e) { console.error(e); }"}Complex Nested Validation
Validates nested objects with various property types.
{"const nestedSchema = zod.object({ user: zod.object({ name: zod.string(), contact: zod.object({ email: zod.string().email(), phone: zod.string() }) }) }); try { nestedSchema.parse({ user: { name: 'Jane', contact: { email: 'jane@example.com', phone: '123-456-7890' } } }); } catch (e) { console.error(e); }"}Custom Validation
Validates that a number is positive using custom validation logic.
{"const positiveNumber = zod.number().positive(); try { positiveNumber.parse(42); } catch (e) { console.error(e); }"}Error Formatting
Formats validation errors for easier debugging and display.
{"const schema = zod.string(); try { schema.parse(42); } catch (e) { console.error(e.format()); }"}Joi is a powerful schema description language and data validator for JavaScript. It offers a similar API to Zod but has been around longer and is often considered more mature. Joi provides a wide range of built-in validators and is highly extensible.
Yup is a JavaScript schema builder for value parsing and validation. It defines a schema with an expressive API and can be used with or without TypeScript. Yup is often used in the context of form validation, especially with libraries like Formik.
Ajv is a JSON Schema Validator. It validates data against JSON Schema (draft 06/07/2019) and is known for its performance. Unlike Zod, which is TypeScript-first, Ajv focuses on JSON Schema validation and is often used for validating data structures in RESTful APIs.
Class-validator allows for validation of class instances based on decorators. It is tightly coupled with TypeScript and uses decorators to define validation rules, which can be more familiar to developers used to working with TypeScript classes and decorators.
⭐️ smash that star button ⭐️
Like typesafety? Check out tRPC — a better way to build end-to-end typesafe APIs without GraphQL or code generation — just TypeScript.
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:
.optional() return a new instanceSponsorship 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.
Deletype deletype.com/ |
Kevin Simper @kevinsimper |
Brandon Bayer @flybayer, creator of Blitz.js |
Bamboo Creative bamboocreative.nz |
Jeremy Banks github.com/jeremyBanks |
Marcato Partners marcatopartners.com |
To get your name + Twitter + website here, sponsor Zod at the Freelancer or Consultancy tier.
To install Zod v3:
npm install zod
⚠️ IMPORTANT: You must enable strict mode in your tsconfig.json. This is a best practice for all TypeScript projects.
// tsconfig.json
{
// ...
"compilerOptions": {
// ...
"strict": true
}
}
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 GraphQLts-to-zod: Convert TypeScript definitions into Zod schemas.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 middlewareszod-to-json-schema: Convert your Zod schemas into JSON Schemas.json-to-zod: Convert JSON objects into Zod schemas. Use it live here.react-hook-form: A first-party Zod resolver for React Hook Formformik: A community-maintained Formik adapter for ZodCreating a simple string schema
import { z } from "zod";
// creating a schema for strings
const mySchema = z.string();
// parsing
mySchema.parse("tuna"); // => "tuna"
mySchema.parse(12); // => throws ZodError
// "safe" parsing (doesn't throw error if validation fails)
mySchema.safeParse("tuna"); // => { success: true; data: "tuna" }
mySchema.safeParse(12); // => { success: false; error: ZodError }
Creating an object schema
import { z } from "zod";
const User = z.object({
username: z.string(),
});
User.parse({ username: "Ludwig" });
// extract the inferred type
type User = z.infer<typeof User>;
// { username: string }
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 undefined
// catch-all types
// allows any value
z.any();
z.unknown();
// never type
// allows no values
z.never();
const tuna = z.literal("tuna");
const twelve = z.literal(12);
const tru = z.literal(true);
// retrieve literal value
tuna.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.
You can customize certain errors when creating a string schema.
const name = z.string({
required: "Name is required",
invalid: "Invalid name",
});
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);
// deprecated, equivalent to .min(1)
z.string().nonempty();
// optional custom error message
z.string().nonempty({ message: "Can't be empty" });
Check out validator.js for a bunch of other useful string validation functions.
You can customize certain errors when creating a string schema.
const name = z.string({
required_error: "Name is required",
invalid_type_error: "Name must be a string",
});
When using validation methods, you can pass in an additional argument to provide a custom error message.
z.string().min(5, { message: "Must be 5 or more characters long" });
z.string().max(5, { message: "Must be 5 or fewer characters long" });
z.string().length(5, { message: "Must be exactly 5 characters long" });
z.string().email({ message: "Invalid email address" });
z.string().url({ message: "Invalid url" });
z.string().uuid({ message: "Invalid UUID" });
You can customize certain error messages when creating a number schema.
const age = z.number({
required_error: "Age is required",
invalid_type_error: "Age must be a number",
});
Zod includes a handful of number-specific validations.
z.number().gt(5);
z.number().gte(5); // alias .min(5)
z.number().lt(5);
z.number().lte(5); // alias .max(5)
z.number().int(); // value must be an integer
z.number().positive(); // > 0
z.number().nonnegative(); // >= 0
z.number().negative(); // < 0
z.number().nonpositive(); // <= 0
z.number().multipleOf(5); // Evenly divisible by 5. Alias .step(5)
Optionally, you can pass in a second argument to provide a custom error message.
z.number().lte(5, { message: "this👏is👏too👏big" });
You can customize certain error messages when creating a boolean schema.
const isActive = z.boolean({
required_error: "isActive is required",
invalid_type_error: "isActive must be a boolean",
});
There are two ways to define enums in Zod.
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(). Alternatively, use as const to define your enum values as a tuple of strings. See the const assertion docs for details.
const VALUES = ["Salmon", "Tuna", "Trout"] as const;
const FishEnum = z.enum(VALUES);
This is not allowed:
const fish = ["Salmon", "Tuna", "Trout"];
const FishEnum = z.enum(fish);
In that case, the inferred type of fish is simply string[], so Zod isn't able to infer the individual enum elements.
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"]);
Zod enums are the recommended approach to defining and validating enums. But if you need to validate against an enum from a third-party library (or you don't want to rewrite your existing enums) you can use z.nativeEnum() .
Numeric enums
enum Fruits {
Apple,
Banana,
}
const FruitEnum = z.nativeEnum(Fruits);
type FruitEnum = z.infer<typeof FruitEnum>; // Fruits
FruitEnum.parse(Fruits.Apple); // passes
FruitEnum.parse(Fruits.Banana); // passes
FruitEnum.parse(0); // passes
FruitEnum.parse(1); // passes
FruitEnum.parse(3); // fails
String enums
enum Fruits {
Apple = "apple",
Banana = "banana",
Cantaloupe, // you can mix numerical and string enums
}
const FruitEnum = z.nativeEnum(Fruits);
type FruitEnum = z.infer<typeof FruitEnum>; // Fruits
FruitEnum.parse(Fruits.Apple); // passes
FruitEnum.parse(Fruits.Cantaloupe); // passes
FruitEnum.parse("apple"); // passes
FruitEnum.parse("banana"); // passes
FruitEnum.parse(0); // passes
FruitEnum.parse("Cantaloupe"); // fails
Const enums
The .nativeEnum() function works for as const objects as well. ⚠️ as const required TypeScript 3.4+!
const Fruits = {
Apple: "apple",
Banana: "banana",
Cantaloupe: 3,
} as const;
const FruitEnum = z.nativeEnum(Fruits);
type FruitEnum = z.infer<typeof FruitEnum>; // "apple" | "banana" | 3
FruitEnum.parse("apple"); // passes
FruitEnum.parse("banana"); // passes
FruitEnum.parse(3); // passes
FruitEnum.parse("Cantaloupe"); // fails
You can 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 };
.unwrapconst stringSchema = z.string();
const optionalString = stringSchema.optional();
optionalString.unwrap() === stringSchema; // true
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
.unwrapconst stringSchema = z.string();
const nullableString = stringSchema.nullable();
nullableString.unwrap() === stringSchema; // true
// 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;
};
.shapeUse .shape to access the schemas for a particular key.
Dog.shape.name; // => string schema
Dog.shape.age; // => number schema
.extendYou 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!
.mergeEquivalent to A.extend(B.shape).
const BaseTeacher = z.object({ students: z.array(z.string()) });
const HasID = z.object({ id: z.string() });
const Teacher = BaseTeacher.merge(HasID);
type Teacher = z.infer<typeof Teacher>; // => { students: string[], id: string }
If the two schemas share keys, the properties of B overrides the property of A. The returned schema also inherits the "unknownKeys" policy (strip/strict/passthrough) and the catchall schema of B.
.pick/.omitInspired 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[] }
.partialInspired by the built-in TypeScript utility type Partial, the .partial method makes all properties optional.
Starting from this object:
const user = z.object({
email: z.string()
username: z.string(),
});
// { email: string; username: string }
We can create a partial version:
const partialUser = user.partial();
// { email?: string | undefined; username?: string | undefined }
You can also specify which properties to make optional:
const optionalEmail = user.partial({
email: true,
});
/*
{
email?: string | undefined;
username: string
}
*/
.deepPartialThe .partial method is shallow — it only applies one level deep. There is also a "deep" version:
const user = z.object({
username: z.string(),
location: z.object({
latitude: z.number(),
longitude: z.number(),
}),
strings: z.array(z.object({ value: z.string() })),
});
const deepPartialUser = user.deepPartial();
/*
{
username?: string | undefined,
location?: {
latitude?: number | undefined;
longitude?: number | undefined;
} | undefined,
strings?: { value?: string}[]
}
*/
Important limitation: deep partials only work as expected in hierarchies of objects, arrays, and tuples.
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
.passthroughInstead, if you want to pass through unknown keys, use .passthrough() .
person.passthrough().parse({
name: "bob dylan",
extraKey: 61,
});
// => { name: "bob dylan", extraKey: 61 }
.strictYou 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
.stripYou can use the .strip method to reset an object schema to the default behavior (stripping unrecognized keys).
.catchallYou 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".
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
.nonemptyIf you want to ensure that an array contains at least one element, use .nonempty().
const nonEmptyStrings = z.string().array().nonempty();
// the inferred type is now
// [string, ...string[]]
nonEmptyStrings.parse([]); // throws: "Array cannot be empty"
nonEmptyStrings.parse(["Ariana Grande"]); // passes
You can optionally specify a custom error message:
// optional custom error message
const nonEmptyStrings = z.string().array().nonempty({
message: "Can't be empty!",
});
.min/.max/.lengthz.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.
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 }]
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());
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
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.
const stringNumberMap = z.map(z.string(), z.number());
type StringNumberMap = z.infer<typeof stringNumberMap>;
// type StringNumber = Map<string, number>
const numberSet = z.set(z.string());
type numberSet = z.infer<typeof numberSet>;
// Set<number>
Intersections are useful for creating "logical AND" types. This is useful for intersecting two object types.
const Person = z.object({
name: z.string(),
});
const Employee = z.object({
role: z.string(),
});
const EmployedPerson = z.intersection(Person, Employee);
// equivalent to:
const EmployedPerson = Person.and(Employee);
Though in many cases, it is recommended to use A.merge(B) to merge two objects. The .merge method returns a new ZodObject instance, whereas A.and(B) returns a less useful ZodIntersection instance that lacks common object methods like pick and omit.
const a = z.union([z.number(), z.string()]);
const b = z.union([z.number(), z.boolean()]);
const c = z.intersection(a, b);
type c = z.infer<typeof c>; // => number
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.
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.
Despite supporting recursive schemas, passing an cyclical data into Zod will cause an infinite loop.
const numberPromise = z.promise(z.number());
"Parsing" works a little differently with promise schemas. Validation happens in two parts:
.then and .catch methods.)..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
};
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
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 functions actually return undefined.)
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[]
Typically Zod operates under a "parse then transform" paradigm. Zod validates the input first, then passes it through a chain of transformation functions. (For more information about transforms, read the .transform docs.)
But sometimes you want to apply some transform to the input before parsing happens. A common use case: type coercion. Zod enables this with the z.preprocess().
const castToString = z.preprocess((val) => String(val), z.string());
This returns a ZodEffects instance. ZodEffects is a wrapper class that contains all logic pertaining to preprocessing, refinements, and transforms.
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
.parseis 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;
}
.safeParseAsyncAlias:
.spa
An asynchronous version of safeParse.
await stringSchema.safeParseAsync("billie");
For convenience, this has been aliased to .spa:
await stringSchema.spa("billie");
.refine.refine(validator: (data:T)=>any, params?: RefineParams)
Zod lets you provide custom validation logic via refinements. (For advanced features like creating multiple issues and customizing error codes, see .superRefine.)
Zod was designed to mirror TypeScript as closely as possible. But there are many so-called "refinement types" you may wish to check for that can't be represented in TypeScript's type system. For instance: checking that a number is an integer or that a string is a valid email address.
For example, you can define a custom validation check on any Zod schema with .refine :
const myString = z.string().refine((val) => val.length <= 255, {
message: "String can't be more than 255 characters",
});
⚠️ Refinement functions should not throw. Instead they should return a falsy value to signal failure.
As you can see, .refine takes two arguments.
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.)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` })
);
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"
}]
}
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
.parseAsyncmethod to parse data! Otherwise Zod will throw an error.
Transforms and refinements can be interleaved:
z.string()
.transform((val) => val.length)
.refine((val) => val > 25);
.superRefineThe .refine method is actually syntactic sugar atop a more versatile (and verbose) method called superRefine. Here's an example:
const Strings = 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 !== new Set(val).size) {
ctx.addIssue({
code: z.ZodIssueCode.custom,
message: `No duplicated 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).
.transformTo transform data after parsing, use the transform method.
const stringToNumber = z.string().transform((val) => myString.length);
stringToNumber.parse("string"); // => 6
⚠️ Transform functions must not throw. Make sure to use refinements before the transform to make sure the input can be parsed by the transform.
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.
const emailToDomain = z
.string()
.email()
.transform((val) => val.split("@")[1]);
emailToDomain.parse("colinhacks@example.com"); // => example.com
Transforms and refinements can be interleaved:
z.string()
.transform((val) => val.length)
.refine((val) => val > 25);
Transforms can also be async.
const IdToUser = z
.string()
.uuid()
.transform(async (id) => {
return await getUserById(id);
});
⚠️ If your schema contains asynchronous transforms, you must use .parseAsync() or .safeParseAsync() to parse data. Otherwise Zod will throw an error.
.defaultYou can use transforms 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
.optionalA convenience method that returns an optional version of a schema.
const optionalString = z.string().optional(); // string | undefined
// equivalent to
z.optional(z.string());
.nullableA convenience method that returns an nullable version of a schema.
const nullableString = z.string().nullable(); // string | null
// equivalent to
z.nullable(z.string());
.nullishA 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" here.
const nullishString = z.string().nullish(); // string | null | undefined
// equivalent to
z.string().optional().nullable();
.arrayA convenience method that returns an array schema for the given type:
const nullableString = z.string().array(); // string[]
// equivalent to
z.array(z.string());
.promiseA convenience method for promise types:
const stringPromise = z.string().promise(); // Promise<string>
// equivalent to
z.promise(z.string());
.orA convenience method for union types.
z.string().or(z.number()); // string | number
// equivalent to
z.union([z.string(), z.number()]);
.andA convenience method for creating intersection types.
z.object({ name: z.string() }).and(z.object({ age: z.number() })); // { name: string } & { age: number }
// equivalent to
z.intersection(z.string(), z.number());
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
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:
const stringToNumber = z.string().transform((val) => val.length);
// ⚠️ Important: z.infer returns the OUTPUT type!
type input = z.input<typeof stringToNumber>; // string
type output = z.output<typeof stringToNumber>; // number
// equivalent to z.output!
type inferred = z.infer<typeof stringToNumber>; // number
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"
}
] */
}
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
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.
Doesn't support static type inference 😕
https://github.com/jquense/yup
Yup is a full-featured library that was implemented first in vanilla JS, and later rewritten in TypeScript.
Differences
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.
fp-ts compatibility[T, ...T[]])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.
[T, ...T[]])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.
View the changelog at CHANGELOG.md
FAQs
TypeScript-first schema declaration and validation library with static type inference
The npm package zod receives a total of 10,658,797 weekly downloads. As such, zod popularity was classified as popular.
We found that zod demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
An advanced npm supply chain attack is leveraging Ethereum smart contracts for decentralized, persistent malware control, evading traditional defenses.
Security News
Research
Attackers are impersonating Sindre Sorhus on npm with a fake 'chalk-node' package containing a malicious backdoor to compromise developers' projects.
Security News
The npm package for the LottieFiles Player web component was hit with a supply chain attack after a software engineer's npmjs credentials were compromised.