+
Zod ✨ https://zod.dev ✨
Zod 3.23 is out! View the release notes .
These docs have been translated into Chinese .
Table of contents
Introduction Zod is a TypeScript-first schema declaration and validation library. I'm using the term "schema" to broadly refer to any data type, from a simple string to a complex nested object.
Zod is designed to be as developer-friendly as possible. The goal is to eliminate duplicative type declarations. With Zod, you declare a validator once and Zod will automatically infer the static TypeScript type. It's easy to compose simpler types into complex data structures.
Some other great aspects:
Zero dependencies Works in Node.js and all modern browsers Tiny: 8kb minified + zipped Immutable: methods (e.g. .optional()) return a new instance Concise, chainable interface Functional approach: parse, don't validate Works with plain JavaScript too! You don't need to use TypeScript. 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 This tier was just added. Be the first Gold Sponsor!
Silver
Bronze
Copper
Brandon Bayer Jiří Brabec Alex Johansson Fungible Systems Adaptable Avana Wallet Jason Lengstorf Global Illumination, Inc. MasterBorn Ryan Palmer Michael Sweeney Nextbase Remotion Connor Sinnott Mohammad-Ali A'râbi Supatool
Ecosystem There are a growing number of tools that are built atop or support Zod natively! If you've built a tool or library on top of Zod, tell me about it on Twitter or start a Discussion . I'll add it below and tweet it out.
Resources API libraries tRPC@anatine/zod-nestjszod-endpointszhttpdomain-functions@zodios/coreexpress-zod-apitapiduckkoa-zod-routerreact-hook-formzod-validation-errorZodErrors.zod-formik-adapterreact-zorm<form> generation and validation for React using Zod.zodixconformremix-params-helperformik-validator-zodzod-i18n-map@modular-forms/solidhouseformsveltekit-superformsmobx-zod-form@vee-validate/zodZod to X X to Zod Mocking @anatine/zod-mockfaker.js .zod-mockingzod-fixturezockerzodockPowered by Zod freerstoresloniksolypastelzod-xlsxznvzod-configUtilities for Zod Installation Requirements From npm (Node/Bun) npm install zod # npm yarn add zod # yarn bun add zod # bun pnpm add zod # pnpm Zod also publishes a canary version on every commit. To install the canary:
npm install zod@canary # npm yarn add zod@canary # yarn bun add zod@canary # bun pnpm add zod@canary # pnpm From deno.land/x (Deno) Unlike Node, Deno relies on direct URL imports instead of a package manager like NPM. Zod is available on deno.land/x . The latest version can be imported like so:
import { z } from "https://deno.land/x/zod/mod.ts"; You can also specify a particular version:
import { z } from "https://deno.land/x/zod@v3.16.1/mod.ts"; The rest of this README assumes you are using npm and importing directly from the "zod" package.
Basic usage Creating a simple string schema
import { z } from "zod"; // creating a schema for strings const mySchema = z.string(); // parsing mySchema.parse("tuna"); // => "tuna" mySchema.parse(12); // => throws ZodError // "safe" parsing (doesn't throw error if validation fails) mySchema.safeParse("tuna"); // => { success: true; data: "tuna" } mySchema.safeParse(12); // => { success: false; error: ZodError } Creating an object schema
import { z } from "zod"; const User = z.object({ username: z.string(), }); User.parse({ username: "Ludwig" }); // extract the inferred type type User = z.infer<typeof User>; // { username: string } Primitives import { z } from "zod"; // primitive values z.string(); z.number(); z.bigint(); z.boolean(); z.date(); z.symbol(); // empty types z.undefined(); z.null(); z.void(); // accepts undefined // catch-all types // allows any value z.any(); z.unknown(); // never type // allows no values z.never(); Coercion for primitives Zod now provides a more convenient way to coerce primitive values.
const schema = z.coerce.string(); schema.parse("tuna"); // => "tuna" schema.parse(12); // => "12" During the parsing step, the input is passed through the String() function, which is a JavaScript built-in for coercing data into strings.
schema.parse(12); // => "12" schema.parse(true); // => "true" schema.parse(undefined); // => "undefined" schema.parse(null); // => "null" The returned schema is a normal ZodString instance so you can use all string methods.
z.coerce.string().email().min(5); How coercion works
All primitive types support coercion. Zod coerces all inputs using the built-in constructors: String(input), Number(input), new Date(input), etc.
z.coerce.string(); // String(input) z.coerce.number(); // Number(input) z.coerce.boolean(); // Boolean(input) z.coerce.bigint(); // BigInt(input) z.coerce.date(); // new Date(input) Note — Boolean coercion with z.coerce.boolean() may not work how you expect. Any truthy value is coerced to true, and any falsy value is coerced to false.
const schema = z.coerce.boolean(); // Boolean(input) schema.parse("tuna"); // => true schema.parse("true"); // => true schema.parse("false"); // => true schema.parse(1); // => true schema.parse([]); // => true schema.parse(0); // => false schema.parse(""); // => false schema.parse(undefined); // => false schema.parse(null); // => false For more control over coercion logic, consider using z.preprocessz.pipe()
Literals Literal schemas represent a literal type , like "hello world" or 5.
const tuna = z.literal("tuna"); const twelve = z.literal(12); const twobig = z.literal(2n); // bigint literal const tru = z.literal(true); const terrificSymbol = Symbol("terrific"); const terrific = z.literal(terrificSymbol); // retrieve literal value tuna.value; // "tuna" Currently there is no support for Date literals in Zod. If you have a use case for this feature, please file an issue.
Strings Zod includes a handful of string-specific validations.
// validations z.string().max(5); z.string().min(5); z.string().length(5); z.string().email(); z.string().url(); z.string().emoji(); z.string().jwt(); // validates format, NOT signature z.string().jwt({ alg: "HS256" }); // specify algorithm z.string().uuid(); z.string().nanoid(); z.string().cuid(); z.string().cuid2(); z.string().ulid(); z.string().xid(); z.string().ksuid(); z.string().regex(regex); z.string().includes(string); z.string().startsWith(string); z.string().endsWith(string); z.string().datetime(); // ISO 8601; by default only `Z` timezone allowed z.string().ip(); // defaults to allow both IPv4 and IPv6 // transforms z.string().trim(); // trim whitespace z.string().toLowerCase(); // toLowerCase z.string().toUpperCase(); // toUpperCase // added in Zod 3.23 z.string().date(); // ISO date format (YYYY-MM-DD) z.string().time(); // ISO time format (HH:mm:ss[.SSSSSS]) z.string().duration(); // ISO 8601 duration z.string().base64(); z.string().e164(); // E.164 number format Check out validator.js for a bunch of other useful string validation functions that can be used in conjunction with Refinements .
You can customize some common error messages when creating a string schema.
const name = z.string({ required_error: "Name is required", invalid_type_error: "Name must be a string", }); When using validation methods, you can pass in an additional argument to provide a custom error message.
z.string().min(5, { message: "Must be 5 or more characters long" }); z.string().max(5, { message: "Must be 5 or fewer characters long" }); z.string().length(5, { message: "Must be exactly 5 characters long" }); z.string().email({ message: "Invalid email address" }); z.string().url({ message: "Invalid url" }); z.string().emoji({ message: "Contains non-emoji characters" }); z.string().uuid({ message: "Invalid UUID" }); z.string().includes("tuna", { message: "Must include tuna" }); z.string().startsWith("https://", { message: "Must provide secure URL" }); z.string().endsWith(".com", { message: "Only .com domains allowed" }); z.string().datetime({ message: "Invalid datetime string! Must be UTC." }); z.string().date({ message: "Invalid date string!" }); z.string().time({ message: "Invalid time string!" }); z.string().ip({ message: "Invalid IP address" }); Datetimes As you may have noticed, Zod string includes a few date/time related validations. These validations are regular expression based, so they are not as strict as a full date/time library. However, they are very convenient for validating user input.
The z.string().datetime() method enforces ISO 8601; default is no timezone offsets and arbitrary sub-second decimal precision.
const datetime = z.string().datetime(); datetime.parse("2020-01-01T00:00:00Z"); // pass datetime.parse("2020-01-01T00:00:00.123Z"); // pass datetime.parse("2020-01-01T00:00:00.123456Z"); // pass (arbitrary precision) datetime.parse("2020-01-01T00:00:00+02:00"); // fail (no offsets allowed) Timezone offsets can be allowed by setting the offset option to true.
const datetime = z.string().datetime({ offset: true }); datetime.parse("2020-01-01T00:00:00+02:00"); // pass datetime.parse("2020-01-01T00:00:00.123+02:00"); // pass (millis optional) datetime.parse("2020-01-01T00:00:00.123+0200"); // pass (millis optional) datetime.parse("2020-01-01T00:00:00.123+02"); // pass (only offset hours) datetime.parse("2020-01-01T00:00:00Z"); // pass (Z still supported) You can additionally constrain the allowable precision. By default, arbitrary sub-second precision is supported (but optional).
const datetime = z.string().datetime({ precision: 3 }); datetime.parse("2020-01-01T00:00:00.123Z"); // pass datetime.parse("2020-01-01T00:00:00Z"); // fail datetime.parse("2020-01-01T00:00:00.123456Z"); // fail Dates Added in Zod 3.23
The z.string().date() method validates strings in the format YYYY-MM-DD.
const date = z.string().date(); date.parse("2020-01-01"); // pass date.parse("2020-1-1"); // fail date.parse("2020-01-32"); // fail Times Added in Zod 3.23
The z.string().time() method validates strings in the format HH:MM:SS[.s+]. The second can include arbitrary decimal precision. It does not allow timezone offsets of any kind.
const time = z.string().time(); time.parse("00:00:00"); // pass time.parse("09:52:31"); // pass time.parse("23:59:59.9999999"); // pass (arbitrary precision) time.parse("00:00:00.123Z"); // fail (no `Z` allowed) time.parse("00:00:00.123+02:00"); // fail (no offsets allowed) You can set the precision option to constrain the allowable decimal precision.
const time = z.string().time({ precision: 3 }); time.parse("00:00:00.123"); // pass time.parse("00:00:00.123456"); // fail time.parse("00:00:00"); // fail IP addresses The z.string().ip() method by default validate IPv4 and IPv6.
const ip = z.string().ip(); ip.parse("192.168.1.1"); // pass ip.parse("84d5:51a0:9114:1855:4cfa:f2d7:1f12:7003"); // pass ip.parse("84d5:51a0:9114:1855:4cfa:f2d7:1f12:192.168.1.1"); // pass ip.parse("256.1.1.1"); // fail ip.parse("84d5:51a0:9114:gggg:4cfa:f2d7:1f12:7003"); // fail You can additionally set the IP version.
const ipv4 = z.string().ip({ version: "v4" }); ipv4.parse("84d5:51a0:9114:1855:4cfa:f2d7:1f12:7003"); // fail const ipv6 = z.string().ip({ version: "v6" }); ipv6.parse("192.168.1.1"); // fail JSON The z.string().json(...) method parses strings as JSON, then pipes the result to another specified schema.
const Env = z.object({ API_CONFIG: z.string().json( z.object({ host: z.string(), port: z.number().min(1000).max(2000), }) ), SOME_OTHER_VALUE: z.string(), }); const env = Env.parse({ API_CONFIG: '{ "host": "example.com", "port": 1234 }', SOME_OTHER_VALUE: "abc123", }); env.API_CONFIG.host; // returns parsed value If invalid JSON is encountered, the syntax error will be wrapped and put into a parse error:
const env = Env.safeParse({ API_CONFIG: "not valid json!", SOME_OTHER_VALUE: "abc123", }); if (!env.success) { console.log(env.error); // ... Unexpected token n in JSON at position 0 ... } This is recommended over using z.string().transform(s => JSON.parse(s)), since that will not catch parse errors, even when using .safeParse.
E.164 telephone numbers The z.string().e164() method can be used to validate international telephone numbers.
const e164Number = z.string().e164(); e164Number.parse("+1555555"); // pass e164Number.parse("+155555555555555"); // pass e164Number.parse("555555555"); // fail e164Number.parse("+1 1555555"); // fail Numbers You can customize certain error messages when creating a number schema.
const age = z.number({ required_error: "Age is required", invalid_type_error: "Age must be a number", }); Zod includes a handful of number-specific validations.
z.number().gt(5); z.number().gte(5); // alias .min(5) z.number().lt(5); z.number().lte(5); // alias .max(5) z.number().int(); // value must be an integer z.number().positive(); // > 0 z.number().nonnegative(); // >= 0 z.number().negative(); // < 0 z.number().nonpositive(); // <= 0 z.number().multipleOf(5); // Evenly divisible by 5. Alias .step(5) z.number().finite(); // value must be finite, not Infinity or -Infinity z.number().safe(); // value must be between Number.MIN_SAFE_INTEGER and Number.MAX_SAFE_INTEGER Optionally, you can pass in a second argument to provide a custom error message.
z.number().lte(5, { message: "this👏is👏too👏big" }); BigInts Zod includes a handful of bigint-specific validations.
z.bigint().gt(5n); z.bigint().gte(5n); // alias `.min(5n)` z.bigint().lt(5n); z.bigint().lte(5n); // alias `.max(5n)` z.bigint().positive(); // > 0n z.bigint().nonnegative(); // >= 0n z.bigint().negative(); // < 0n z.bigint().nonpositive(); // <= 0n z.bigint().multipleOf(5n); // Evenly divisible by 5n. NaNs You can customize certain error messages when creating a nan schema.
const isNaN = z.nan({ required_error: "isNaN is required", invalid_type_error: "isNaN must be 'not a number'", }); Booleans You can customize certain error messages when creating a boolean schema.
const isActive = z.boolean({ required_error: "isActive is required", invalid_type_error: "isActive must be a boolean", }); Dates Use z.date() to validate Date instances.
z.date().safeParse(new Date()); // success: true z.date().safeParse("2022-01-12T00:00:00.000Z"); // success: false You can customize certain error messages when creating a date schema.
const myDateSchema = z.date({ required_error: "Please select a date and time", invalid_type_error: "That's not a date!", }); Zod provides a handful of date-specific validations.
z.date().min(new Date("1900-01-01"), { message: "Too old" }); z.date().max(new Date(), { message: "Too young!" }); Coercion to Date
Since zod 3.20 , use z.coerce.date()new Date(input).
const dateSchema = z.coerce.date(); type DateSchema = z.infer<typeof dateSchema>; // type DateSchema = Date /* valid dates */ console.log(dateSchema.safeParse("2023-01-10T00:00:00.000Z").success); // true console.log(dateSchema.safeParse("2023-01-10").success); // true console.log(dateSchema.safeParse("1/10/23").success); // true console.log(dateSchema.safeParse(new Date("1/10/23")).success); // true /* invalid dates */ console.log(dateSchema.safeParse("2023-13-10").success); // false console.log(dateSchema.safeParse("0000-00-00").success); // false For older zod versions, use z.preprocessdescribed in this thread .
Files (Browser only) Use z.file() to validate File instances.
z.file().safeParse(new File(["foobar"], "foobar.txt", { type: "text/plain" })); // success: true z.file().safeParse("foobar"); // success: false You can customize certain error messages when creating a file schema.
const myFileSchema = z.file({ required_error: "Please select a file", invalid_type_error: "That's not a file!", }); Zod provides a handful of file-specific validations.
z.file().min(100, { message: "Too small" }); z.file().max(10_000, { message: "Too large!" }); z.file().accept([".txt", ".csv"], { message: "Accepted file types: .txt, .csv", }); z.file().accept(["text/plain"], { message: "Accepted file type: text/plain", }); z.file().filename(z.string().min(3), { message: "Filename must be at least 3 characters long", }); Zod enums const FishEnum = z.enum(["Salmon", "Tuna", "Trout"]); type FishEnum = z.infer<typeof FishEnum>; // 'Salmon' | 'Tuna' | 'Trout' z.enum is a Zod-native way to declare a schema with a fixed set of allowable string values. Pass the array of values directly into z.enum(). Alternatively, use as const to define your enum values as a tuple of strings. See the const assertion docs for details.
const VALUES = ["Salmon", "Tuna", "Trout"] as const; const FishEnum = z.enum(VALUES); This is not allowed, since Zod isn't able to infer the exact values of each element.
const fish = ["Salmon", "Tuna", "Trout"]; const FishEnum = z.enum(fish); .enum
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"]; .exclude/.extract()
You can create subsets of a Zod enum with the .exclude and .extract methods.
const FishEnum = z.enum(["Salmon", "Tuna", "Trout"]); const SalmonAndTrout = FishEnum.extract(["Salmon", "Trout"]); const TunaOnly = FishEnum.exclude(["Salmon", "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 requires TypeScript 3.4+!
const Fruits = { Apple: "apple", Banana: "banana", Cantaloupe: 3, } as const; const FruitEnum = z.nativeEnum(Fruits); type FruitEnum = z.infer<typeof FruitEnum>; // "apple" | "banana" | 3 FruitEnum.parse("apple"); // passes FruitEnum.parse("banana"); // passes FruitEnum.parse(3); // passes FruitEnum.parse("Cantaloupe"); // fails You can access the underlying object with the .enum property:
FruitEnum.enum.Apple; // "apple" Optionals You can make any schema optional with z.optional(). This wraps the schema in a ZodOptional instance and returns the result.
const schema = z.optional(z.string()); schema.parse(undefined); // => returns undefined type A = z.infer<typeof schema>; // string | undefined For convenience, you can also call the .optional() method on an existing schema.
const user = z.object({ username: z.string().optional(), }); type C = z.infer<typeof user>; // { username?: string | undefined }; You can extract the wrapped schema from a ZodOptional instance with .unwrap().
const stringSchema = z.string(); stringSchema; // true
const optionalString = stringSchema.optional(); optionalString.unwrap()Nullables Similarly, you can create nullable types with z.nullable().
const nullableString = z.nullable(z.string()); nullableString.parse("asdf"); // => "asdf" nullableString.parse(null); // => null Or use the .nullable() method.
const E = z.string().nullable(); // equivalent to nullableString type E = z.infer<typeof E>; // string | null Extract the inner schema with .unwrap().
const stringSchema = z.string(); stringSchema; // true
const nullableString = stringSchema.nullable(); nullableString.unwrap()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; }; .shapeUse .shape to access the schemas for a particular key.
Dog.shape.name; // => string schema Dog.shape.age; // => number schema .keyofUse .keyof to create a ZodEnum schema from the keys of an object schema.
const keySchema = Dog.keyof(); keySchema; // ZodEnum<["name", "age"]> .extendYou can add additional fields to an object schema with the .extend method.
const DogWithBreed = Dog.extend({ breed: z.string(), }); You can use .extend to overwrite fields! Be careful with this power!
.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.
.requiredContrary to the .partial method, the .required method makes all properties required.
Starting from this object:
const user = z .object({ email: z.string(), username: z.string(), }) .partial(); // { email?: string | undefined; username?: string | undefined } We can create a required version:
const requiredUser = user.required(); // { email: string; username: string } You can also specify which properties to make required:
const requiredEmail = user.required({ email: true, }); /* { email: string; username?: string | undefined; } */ .passthroughBy default Zod object schemas strip out unrecognized keys during parsing.
const person = z.object({ name: z.string(), }); person.parse({ name: "bob dylan", extraKey: 61, }); // => { name: "bob dylan" } // extraKey has been stripped Instead, if you want to pass through unknown keys, use .passthrough() .
person.passthrough().parse({ name: "bob dylan", extraKey: 61, }); // => { name: "bob dylan", extraKey: 61 } .strictBy default Zod object schemas strip out unrecognized keys during parsing. You can disallow unknown keys with .strict() . If there are any unknown keys in the input, Zod will throw an error.
const person = z .object({ name: z.string(), }) .strict(); person.parse({ name: "bob dylan", extraKey: 61, }); // => throws ZodError .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".
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 .elementUse .element to access the schema for an element of the array.
stringArray.element; // => string schema .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.
.unique// All elements must be unique z.object({ id: z.string() }).array().unique(); // All elements must be unique based on the id property z.object({ id: z.string(), name: z.string() }) .array() .unique({ identifier: (elt) => elt.id }); Tuples Unlike arrays, tuples have a fixed number of elements and each element can have a different type.
const athleteSchema = z.tuple([ z.string(), // name z.number(), // jersey number z.object({ pointsScored: z.number(), }), // statistics ]); type Athlete = z.infer<typeof athleteSchema>; // type Athlete = [string, number, { pointsScored: number }] A variadic ("rest") argument can be added with the .rest method.
const variadicTuple = z.tuple([z.string()]).rest(z.number()); const result = variadicTuple.parse(["hello", 1, 2, 3]); // => [string, ...number[]]; Unions Zod includes a built-in z.union method for composing "OR" types.
const stringOrNumber = z.union([z.string(), z.number()]); stringOrNumber.parse("foo"); // passes stringOrNumber.parse(14); // passes Zod will test the input against each of the "options" in order and return the first value that validates successfully.
For convenience, you can also use the .or method
const stringOrNumber = z.string().or(z.number()); Optional string validation:
To validate an optional form input, you can union the desired string validation with an empty string literal .
This example validates an input that is optional but needs to contain a valid URL :
const optionalUrl = z.union([z.string().url().nullish(), z.literal("")]); console.log(optionalUrl.safeParse(undefined).success); // true console.log(optionalUrl.safeParse(null).success); // true console.log(optionalUrl.safeParse("").success); // true console.log(optionalUrl.safeParse("https://zod.dev").success); // true console.log(optionalUrl.safeParse("not a valid url").success); // false Discriminated unions A discriminated union is a union of object schemas that all share a particular key.
type MyUnion = | { status: "success"; data: string } | { status: "failed"; error: Error }; Such unions can be represented with the z.discriminatedUnion method. This enables faster evaluation, because Zod can check the discriminator key (status in the example above) to determine which schema should be used to parse the input. This makes parsing more efficient and lets Zod report friendlier errors.
With the basic union method, the input is tested against each of the provided "options", and in the case of invalidity, issues for all the "options" are shown in the zod error. On the other hand, the discriminated union allows for selecting just one of the "options", testing against it, and showing only the issues related to this "option".
const myUnion = z.discriminatedUnion("status", [ z.object({ status: z.literal("success"), data: z.string() }), z.object({ status: z.literal("failed"), error: z.instanceof(Error) }), ]); myUnion.parse({ status: "success", data: "yippie ki yay" }); You can extract a reference to the array of schemas with the .options property.
myUnion.options; // [ZodObject<...>, ZodObject<...>] To merge two or more discriminated unions, use .options with destructuring.
const A = z.discriminatedUnion("status", [ /* options */ ]); const B = z.discriminatedUnion("status", [ /* options */ ]); const AB = z.discriminatedUnion("status", [...A.options, ...B.options]); Records Record schemas are used to validate types such as Record<string, number>. This is particularly useful for storing or caching items by ID.
Instanceof You can use z.instanceof to check that the input is an instance of a class. This is useful to validate inputs against classes that are exported from third-party libraries.
class Test { name: string; } const TestSchema = z.instanceof(Test); const blob: any = "whatever"; TestSchema.parse(new Test()); // passes TestSchema.parse(blob); // throws Functions Zod also lets you define "function schemas". This makes it easy to validate the inputs and outputs of a function without intermixing your validation code and "business logic".
You can create a function schema with z.function(args, returnType) .
const myFunction = z.function(); type myFunction = z.infer<typeof myFunction>; // => ()=>unknown Define inputs and outputs.
const myFunction = z .function() .args(z.string(), z.number()) // accepts an arbitrary number of arguments .returns(z.boolean()); type myFunction = z.infer<typeof myFunction>; // => (arg0: string, arg1: number)=>boolean
Template literals TypeScript supports template literal types , which are strings that conform to a statically known structure.
type simpleTemplate = `Hello, ${string}!`; type urlTemplate = `${"http" | "https"}://${string}.${`com` | `net`}`; type pxTemplate = `${number}px`; These types can be represented in Zod with z.literal.template(). Template literals consist of interleaved literals and schemas .
z.literal.template(["Hello, ", z.string()]); // infers to `Hello ${string}` The literal components can be any string, number, boolean, null, or undefined.
z.literal.template(["Hello", 3.14, true, null, undefined]); // infers to `Hello3.14truenullundefined` The schema components can be any literal, primitive, or enum schema.
Note — Refinements, transforms, and pipelines are not supported.
z.template.literal([ z.string(), z.number(), z.boolean(), z.bigint(), z.any(), z.literal("foo"), z.null(), z.undefined(), z.enum(["bar"]), ]); For "union" types like z.boolean() or z.enum(), the inferred static type will be a union of the possible values.
z.literal.template([z.boolean(), z.number()]); // `true${number}` | `false${number}` z.literal.template(["is_", z.enum(["red", "green", "blue"])]); // `is_red` | `is_green` | `is_blue` Examples URL:
const url = z.literal.template([ "https://", z.string(), ".", z.enum(["com", "net"]), ]); // infers to `https://${string}.com` | `https://${string}.net`. url.parse("https://google.com"); // passes url.parse("https://google.net"); // passes url.parse("http://google.com"); // throws url.parse("https://.com"); // throws url.parse("https://google"); // throws url.parse("https://google."); // throws url.parse("https://google.gov"); // throws CSS Measurement:
const measurement = z.literal.template([ z.number().finite(), z.enum(["px", "em", "rem", "vh", "vw", "vmin", "vmax"]), ]); // infers to `${number}` | `${number}px` | `${number}em` | `${number}rem` | `${number}vh` | `${number}vw` | `${number}vmin` | `${number}vmax MongoDB connection string:
const connectionString = z.literal.template([ "mongodb://", z.literal .template([ z.string().regex(/\w+/).describe("username"), ":", z.string().regex(/\w+/).describe("password"), "@", ]) .optional(), z.string().regex(/\w+/).describe("host"), ":", z.number().finite().int().positive().describe("port"), z.literal .template([ "/", z.string().regex(/\w+/).optional().describe("defaultauthdb"), z.literal .template(["?", z.string().regex(/^\w+=\w+(&\w+=\w+)*$/)]) .optional() .describe("options"), ]) .optional(), ]); // inferred type: // | `mongodb://${string}:${number}` // | `mongodb://${string}:${string}@${string}:${number}` // | `mongodb://${string}:${number}/${string}` // | `mongodb://${string}:${string}@${string}:${number}/${string}` // | `mongodb://${string}:${number}/${string}?${string}` // | `mongodb://${string}:${string}@${string}:${number}/${string}?${string}`; Preprocess Zod now supports primitive coercion without the need for .preprocess(). See the coercion docs for more information.
Typically Zod operates under a "parse then transform" paradigm. Zod validates the input first, then passes it through a chain of transformation functions. (For more information about transforms, read the .transform docs .)
But sometimes you want to apply some transform to the input before parsing happens. A common use case: type coercion. Zod enables this with the z.preprocess().
const castToString = z.preprocess((val) => String(val), z.string()); This returns a ZodEffects instance. ZodEffects is a wrapper class that contains all logic pertaining to preprocessing, refinements, and transforms.
Custom schemas You can create a Zod schema for any TypeScript type by using z.custom(). This is useful for creating schemas for types that are not supported by Zod out of the box, such as template string literals.
const px = z.custom<`${number}px`>((val) => { "string" ? /^\d+px$/.test(val) : false;
}); type px = z.infer<typeof px>; // `${number}px` px.parse("42px"); // "42px" px.parse("42vw"); // throws;If you don't provide a validation function, Zod will allow any value. This can be dangerous!
z.custom<{ arg: string }>(); // performs no validation You can customize the error message and other options by passing a second argument. This parameter works the same way as the params parameter of .refine
z.custom<...>((val) => ..., "custom error message"); Schema methods All Zod schemas contain certain methods.
.parse.parse(data: unknown): T
Given any Zod schema, you can call its .parse method to check data is valid. If it is, a value is returned with full type information! Otherwise, an error is thrown.
IMPORTANT: The value returned by .parse is a deep clone of the variable you passed in.
const stringSchema = z.string(); stringSchema.parse("fish"); // => returns "fish" stringSchema.parse(12); // throws error .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 <= 8); await stringSchema.parseAsync("hello"); // => returns "hello" await stringSchema.parseAsync("hello world"); // => throws error .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.
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.
const longString = z.string().refine( (val) => val.length > 10, (val) => ({ message: `${val} is not more than 10 characters` }) ); Customize error path const passwordForm = z data.confirm, {
.object({ password: z.string(), confirm: z.string(), }) .refine((data) => data.passwordmessage: "Passwords don't match", path: ["confirm"], // path of error }); passwordForm.parse({ password: "asdf", confirm: "qwer" });Because you provided a path parameter, the resulting error will be:
ZodError { issues: [{ "code": "custom", "path": [ "confirm" ], "message": "Passwords don't match" }] } Asynchronous refinements Refinements can also be async:
const userId = z.string().refine(async (id) => { // verify that ID exists in database return true; }); ⚠️ If you use async refinements, you must use the .parseAsync method to parse data! Otherwise Zod will throw an error.
Transforms and refinements can be interleaved:
z.string() .transform((val) => val.length) .refine((val) => val > 25);
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 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 promise schemas Missing function schemas Runtypes https://github.com/pelotom/runtypes
Good type inference support.
Supports "pattern matching": computed properties that distribute over unions 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
+ 
+ 
+
+ 
+
+ 
+
+ 
+
+ 
+
+ 
+
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+