Zod

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

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

> Zod 3.23 is out! View the [release notes](https://github.com/colinhacks/zod/releases/tag/v3.23.0). > These docs have been translated into [Chinese](./README_ZH.md). ## Table of contents - [Table of contents](#table-of-contents) - [Introduction](#introduction) - [Sponsors](#sponsors) - [Gold](#gold) - [Silver](#silver) - [Bronze](#bronze) - [Copper](#copper) - [Ecosystem](#ecosystem) - [Resources](#resources) - [API libraries](#api-libraries) - [Form integrations](#form-integrations) - [Zod to X](#zod-to-x) - [X to Zod](#x-to-zod) - [Mocking](#mocking) - [Powered by Zod](#powered-by-zod) - [Utilities for Zod](#utilities-for-zod) - [Installation](#installation) - [Requirements](#requirements) - [From `npm` (Node/Bun)](#from-npm-nodebun) - [From `deno.land/x` (Deno)](#from-denolandx-deno) - [Basic usage](#basic-usage) - [Primitives](#primitives) - [Coercion for primitives](#coercion-for-primitives) - [Literals](#literals) - [Strings](#strings) - [Datetimes](#datetimes) - [Dates](#dates) - [Times](#times) - [IP addresses](#ip-addresses) - [Numbers](#numbers) - [BigInts](#bigints) - [NaNs](#nans) - [Booleans](#booleans) - [Dates](#dates) - [Zod enums](#zod-enums) - [Native enums](#native-enums) - [Optionals](#optionals) - [Nullables](#nullables) - [Objects](#objects) - [`.shape`](#shape) - [`.keyof`](#keyof) - [`.extend`](#extend) - [`.merge`](#merge) - [`.pick/.omit`](#pickomit) - [`.partial`](#partial) - [`.deepPartial`](#deeppartial) - [`.required`](#required) - [`.passthrough`](#passthrough) - [`.strict`](#strict) - [`.strip`](#strip) - [`.catchall`](#catchall) - [Arrays](#arrays) - [`.element`](#element) - [`.nonempty`](#nonempty) - [`.min/.max/.length`](#minmaxlength) - [Tuples](#tuples) - [Unions](#unions) - [Discriminated unions](#discriminated-unions) - [Records](#records) - [Record key type](#record-key-type) - [Maps](#maps) - [Sets](#sets) - [Intersections](#intersections) - [Recursive types](#recursive-types) - [ZodType with ZodEffects](#zodtype-with-zodeffects) - [JSON type](#json-type) - [Cyclical objects](#cyclical-objects) - [Promises](#promises) - [Instanceof](#instanceof) - [Functions](#functions) - [Preprocess](#preprocess) - [Custom schemas](#custom-schemas) - [Schema methods](#schema-methods) - [`.parse`](#parse) - [`.parseAsync`](#parseasync) - [`.safeParse`](#safeparse) - [`.safeParseAsync`](#safeparseasync) - [`.refine`](#refine) - [Arguments](#arguments) - [Customize error path](#customize-error-path) - [Asynchronous refinements](#asynchronous-refinements) - [Relationship to transforms](#relationship-to-transforms) - [`.superRefine`](#superrefine) - [Abort early](#abort-early) - [Type refinements](#type-refinements) - [`.transform`](#transform) - [Chaining order](#chaining-order) - [Validating during transform](#validating-during-transform) - [Relationship to refinements](#relationship-to-refinements) - [Async transforms](#async-transforms) - [`.default`](#default) - [`.describe`](#describe) - [`.catch`](#catch) - [`.optional`](#optional) - [`.nullable`](#nullable) - [`.nullish`](#nullish) - [`.array`](#array) - [`.promise`](#promise) - [`.or`](#or) - [`.and`](#and) - [`.brand`](#brand) - [`.readonly`](#readonly) - [`.pipe`](#pipe) - [You can use `.pipe()` to fix common issues with `z.coerce`.](#you-can-use-pipe-to-fix-common-issues-with-zcoerce) - [Guides and concepts](#guides-and-concepts) - [Type inference](#type-inference) - [Writing generic functions](#writing-generic-functions) - [Constraining allowable inputs](#constraining-allowable-inputs) - [Error handling](#error-handling) - [Error formatting](#error-formatting) - [Comparison](#comparison) - [Joi](#joi) - [Yup](#yup) - [io-ts](#io-ts) - [Runtypes](#runtypes) - [Ow](#ow) - [Changelog](#changelog) ## Introduction Zod is a TypeScript-first schema declaration and validation library. I'm using the term "schema" to broadly refer to any data type, from a simple `string` to a complex nested object. Zod is designed to be as developer-friendly as possible. The goal is to eliminate duplicative type declarations. With Zod, you declare a validator _once_ and Zod will automatically infer the static TypeScript type. It's easy to compose simpler types into complex data structures. Some other great aspects: - Zero dependencies - Works in Node.js and all modern browsers - Tiny: 8kb minified + zipped - Immutable: methods (e.g. `.optional()`) return a new instance - Concise, chainable interface - Functional approach: [parse, don't validate](https://lexi-lambda.github.io/blog/2019/11/05/parse-don-t-validate/) - Works with plain JavaScript too! You don't need to use TypeScript. ### Sponsors Sponsorship at any level is appreciated and encouraged. For individual developers, consider the [Cup of Coffee tier](https://github.com/sponsors/colinhacks). If you built a paid product using Zod, consider one of the [podium tiers](https://github.com/sponsors/colinhacks). #### Gold > This tier was just added. [Be the first Gold Sponsor!](https://github.com/sponsors/colinhacks/sponsorships?sponsor=colinhacks&tier_id=399648&preview=false) #### Silver

Cerbos	Scalar	Speakeasy	Deletype	Trigger.dev
Transloadit	Infisical	Whop	CryptoJobsList	Plain.
Inngest	Storyblok	Mux	`@emreb`

#### Bronze

Numeric	Marcato Partners	Interval	Seasoned Software
Bamboo Creative

#### 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
Social Crow

### 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](https://twitter.com/colinhacks) or [start a Discussion](https://github.com/colinhacks/zod/discussions). I'll add it below and tweet it out. #### Resources - [Total TypeScript Zod Tutorial](https://www.totaltypescript.com/tutorials/zod) by [@mattpocockuk](https://twitter.com/mattpocockuk) - [Fixing TypeScript's Blindspot: Runtime Typechecking](https://www.youtube.com/watch?v=rY_XqfSHock) by [@jherr](https://twitter.com/jherr) #### API libraries - [`tRPC`](https://github.com/trpc/trpc): Build end-to-end typesafe APIs without GraphQL. - [`@anatine/zod-nestjs`](https://github.com/anatine/zod-plugins/tree/main/packages/zod-nestjs): Helper methods for using Zod in a NestJS project. - [`zod-endpoints`](https://github.com/flock-community/zod-endpoints): Contract-first strictly typed endpoints with Zod. OpenAPI compatible. - [`zhttp`](https://github.com/evertdespiegeleer/zhttp): An OpenAPI compatible, strictly typed http library with Zod input and response validation. - [`domain-functions`](https://github.com/SeasonedSoftware/domain-functions/): Decouple your business logic from your framework using composable functions. With first-class type inference from end to end powered by Zod schemas. - [`@zodios/core`](https://github.com/ecyrbe/zodios): A typescript API client with runtime and compile time validation backed by axios and zod. - [`express-zod-api`](https://github.com/RobinTail/express-zod-api): Build Express-based APIs with I/O schema validation and custom middlewares. - [`tapiduck`](https://github.com/sumukhbarve/monoduck/blob/main/src/tapiduck/README.md): End-to-end typesafe JSON APIs with Zod and Express; a bit like tRPC, but simpler. - [`koa-zod-router`](https://github.com/JakeFenley/koa-zod-router): Create typesafe routes in Koa with I/O validation using Zod. #### Form integrations - [`react-hook-form`](https://github.com/react-hook-form/resolvers#zod): A first-party Zod resolver for React Hook Form. - [`zod-validation-error`](https://github.com/causaly/zod-validation-error): Generate user-friendly error messages from `ZodError`s. - [`zod-formik-adapter`](https://github.com/robertLichtnow/zod-formik-adapter): A community-maintained Formik adapter for Zod. - [`react-zorm`](https://github.com/esamattis/react-zorm): Standalone `

` generation and validation for React using Zod. - [`zodix`](https://github.com/rileytomasek/zodix): Zod utilities for FormData and URLSearchParams in Remix loaders and actions. - [`conform`](https://conform.guide/api/zod/parseWithZod): A typesafe form validation library for progressive enhancement of HTML forms. Works with Remix and Next.js. - [`remix-params-helper`](https://github.com/kiliman/remix-params-helper): Simplify integration of Zod with standard URLSearchParams and FormData for Remix apps. - [`formik-validator-zod`](https://github.com/glazy/formik-validator-zod): Formik-compliant validator library that simplifies using Zod with Formik. - [`zod-i18n-map`](https://github.com/aiji42/zod-i18n): Useful for translating Zod error messages. - [`@modular-forms/solid`](https://github.com/fabian-hiller/modular-forms): Modular form library for SolidJS that supports Zod for validation. - [`houseform`](https://github.com/crutchcorn/houseform/): A React form library that uses Zod for validation. - [`sveltekit-superforms`](https://github.com/ciscoheat/sveltekit-superforms): Supercharged form library for SvelteKit with Zod validation. - [`mobx-zod-form`](https://github.com/MonoidDev/mobx-zod-form): Data-first form builder based on MobX & Zod. - [`@vee-validate/zod`](https://github.com/logaretm/vee-validate/tree/main/packages/zod): Form library for Vue.js with Zod schema validation. #### Zod to X - [`zod-to-ts`](https://github.com/sachinraja/zod-to-ts): Generate TypeScript definitions from Zod schemas. - [`zod-to-json-schema`](https://github.com/StefanTerdell/zod-to-json-schema): Convert your Zod schemas into [JSON Schemas](https://json-schema.org/). - [`@anatine/zod-openapi`](https://github.com/anatine/zod-plugins/tree/main/packages/zod-openapi): Converts a Zod schema to an OpenAPI v3.x `SchemaObject`. - [`zod-fast-check`](https://github.com/DavidTimms/zod-fast-check): Generate `fast-check` arbitraries from Zod schemas. - [`zod-dto`](https://github.com/kbkk/abitia/tree/master/packages/zod-dto): Generate Nest.js DTOs from a Zod schema. - [`fastify-type-provider-zod`](https://github.com/turkerdev/fastify-type-provider-zod): Create Fastify type providers from Zod schemas. - [`zod-to-openapi`](https://github.com/asteasolutions/zod-to-openapi): Generate full OpenAPI (Swagger) docs from Zod, including schemas, endpoints & parameters. - [`nestjs-graphql-zod`](https://github.com/incetarik/nestjs-graphql-zod): Generates NestJS GraphQL model classes from Zod schemas. Provides GraphQL method decorators working with Zod schemas. - [`zod-openapi`](https://github.com/samchungy/zod-openapi): Create full OpenAPI v3.x documentation from Zod schemas. - [`fastify-zod-openapi`](https://github.com/samchungy/fastify-zod-openapi): Fastify type provider, validation, serialization and @fastify/swagger support for Zod schemas. - [`typeschema`](https://typeschema.com/): Universal adapter for schema validation. #### X to Zod - [`ts-to-zod`](https://github.com/fabien0102/ts-to-zod): Convert TypeScript definitions into Zod schemas. - [`@runtyping/zod`](https://github.com/johngeorgewright/runtyping/tree/master/packages/zod): Generate Zod from static types & JSON schema. - [`json-schema-to-zod`](https://github.com/StefanTerdell/json-schema-to-zod): Convert your [JSON Schemas](https://json-schema.org/) into Zod schemas. [Live demo](https://StefanTerdell.github.io/json-schema-to-zod-react/). - [`json-to-zod`](https://github.com/rsinohara/json-to-zod): Convert JSON objects into Zod schemas. [Live demo](https://rsinohara.github.io/json-to-zod-react/). - [`graphql-codegen-typescript-validation-schema`](https://github.com/Code-Hex/graphql-codegen-typescript-validation-schema): GraphQL Code Generator plugin to generate form validation schema from your GraphQL schema. - [`zod-prisma`](https://github.com/CarterGrimmeisen/zod-prisma): Generate Zod schemas from your Prisma schema. - [`Supervillain`](https://github.com/Southclaws/supervillain): Generate Zod schemas from your Go structs. - [`prisma-zod-generator`](https://github.com/omar-dulaimi/prisma-zod-generator): Emit Zod schemas from your Prisma schema. - [`prisma-trpc-generator`](https://github.com/omar-dulaimi/prisma-trpc-generator): Emit fully implemented tRPC routers and their validation schemas using Zod. - [`zod-prisma-types`](https://github.com/chrishoermann/zod-prisma-types) Create Zod types from your Prisma models. - [`quicktype`](https://app.quicktype.io/): Convert JSON objects and JSON schemas into Zod schemas. - [`@sanity-typed/zod`](https://github.com/saiichihashimoto/sanity-typed/tree/main/packages/zod): Generate Zod Schemas from [Sanity Schemas](https://www.sanity.io/docs/schema-types). - [`java-to-zod`](https://github.com/ivangreene/java-to-zod): Convert POJOs to Zod schemas - [`Orval`](https://github.com/anymaniax/orval): Generate Zod schemas from OpenAPI schemas #### Mocking - [`@anatine/zod-mock`](https://github.com/anatine/zod-plugins/tree/main/packages/zod-mock): Generate mock data from a Zod schema. Powered by [faker.js](https://github.com/faker-js/faker). - [`zod-mocking`](https://github.com/dipasqualew/zod-mocking): Generate mock data from your Zod schemas. - [`zod-fixture`](https://github.com/timdeschryver/zod-fixture): Use your zod schemas to automate the generation of non-relevant test fixtures in a deterministic way. - [`zocker`](https://zocker.sigrist.dev): Generate plausible mock-data from your schemas. - [`zodock`](https://github.com/ItMaga/zodock) Generate mock data based on Zod schemas. #### Powered by Zod - [`freerstore`](https://github.com/JacobWeisenburger/freerstore): Firestore cost optimizer. - [`slonik`](https://github.com/gajus/slonik/tree/gajus/add-zod-validation-backwards-compatible#runtime-validation-and-static-type-inference): Node.js Postgres client with strong Zod integration. - [`soly`](https://github.com/mdbetancourt/soly): Create CLI applications with zod. - [`pastel`](https://github.com/vadimdemedes/pastel): Create CLI applications with react, zod, and ink. - [`zod-xlsx`](https://github.com/sidwebworks/zod-xlsx): A xlsx based resource validator using Zod schemas. - [`znv`](https://github.com/lostfictions/znv): Type-safe environment parsing and validation for Node.js with Zod schemas. - [`zod-config`](https://github.com/alexmarqs/zod-config): Load configurations across multiple sources with flexible adapters, ensuring type safety with Zod. #### Utilities for Zod - [`zod_utilz`](https://github.com/JacobWeisenburger/zod_utilz): Framework agnostic utilities for Zod. - [`zod-playground`](https://github.com/marilari88/zod-playground): A tool for learning and testing Zod schema validation functionalities. [Link](https://zod-playground.vercel.app/). - [`zod-sandbox`](https://github.com/nereumelo/zod-sandbox): Controlled environment for testing zod schemas. [Live demo](https://zod-sandbox.vercel.app/). - [`zod-dev`](https://github.com/schalkventer/zod-dev): Conditionally disables Zod runtime parsing in production. - [`zod-accelerator`](https://github.com/duplojs/duplojs-zod-accelerator): Accelerates Zod's throughput up to ~100x. ## Installation ### Requirements - TypeScript 4.5+! - You must enable `strict` mode in your `tsconfig.json`. This is a best practice for all TypeScript projects. ```ts // tsconfig.json { // ... "compilerOptions": { // ... "strict": true } } ``` ### From `npm` (Node/Bun) ```sh 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: ```sh 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](https://deno.land/x). The latest version can be imported like so: ```ts import { z } from "https://deno.land/x/zod/mod.ts"; ``` You can also specify a particular version: ```ts 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 ```ts 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 ```ts import { z } from "zod"; const User = z.object({ username: z.string(), }); User.parse({ username: "Ludwig" }); // extract the inferred type type User = z.infer; // { username: string } ``` ## Primitives ```ts 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. ```ts 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. ```ts 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. ```ts 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. ```ts 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](https://developer.mozilla.org/en-US/docs/Glossary/Truthy) value is coerced to `true`, and any [falsy](https://developer.mozilla.org/en-US/docs/Glossary/Falsy) value is coerced to `false`. ```ts 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.preprocess`](#preprocess) or [`z.pipe()`](#pipe). ## Literals Literal schemas represent a [literal type](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types), like `"hello world"` or `5`. ```ts 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. ```ts // validations z.string().max(5); z.string().min(5); z.string().length(5); z.string().email(); z.string().url(); z.string().emoji(); z.string().uuid(); z.string().nanoid(); z.string().cuid(); z.string().cuid2(); z.string().ulid(); 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(); ``` > Check out [validator.js](https://github.com/validatorjs/validator.js) for a bunch of other useful string validation functions that can be used in conjunction with [Refinements](#refine). You can customize some common error messages when creating a string schema. ```ts 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. ```ts 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. ```ts 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`. ```ts 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). ```ts 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`. ```ts 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. ```ts 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. ```ts 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. ```ts 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`. ```ts 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 ``` ## Numbers You can customize certain error messages when creating a number schema. ```ts 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. ```ts 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. ```ts z.number().lte(5, { message: "this👏is👏too👏big" }); ``` ## BigInts Zod includes a handful of bigint-specific validations. ```ts 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. ```ts 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. ```ts 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. ```ts 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. ```ts 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. ```ts 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](https://github.com/colinhacks/zod/releases/tag/v3.20), use [`z.coerce.date()`](#coercion-for-primitives) to pass the input through `new Date(input)`. ```ts const dateSchema = z.coerce.date(); type DateSchema = z.infer; // 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.preprocess`](#preprocess) like [described in this thread](https://github.com/colinhacks/zod/discussions/879#discussioncomment-2036276). ## Zod enums ```ts const FishEnum = z.enum(["Salmon", "Tuna", "Trout"]); type FishEnum = z.infer; // '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](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-4.html#const-assertions) for details. ```ts 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. ```ts 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: ```ts 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: ```ts FishEnum.options; // ["Salmon", "Tuna", "Trout"]; ``` **`.exclude/.extract()`** You can create subsets of a Zod enum with the `.exclude` and `.extract` methods. ```ts 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** ```ts enum Fruits { Apple, Banana, } const FruitEnum = z.nativeEnum(Fruits); type FruitEnum = z.infer; // 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** ```ts enum Fruits { Apple = "apple", Banana = "banana", Cantaloupe, // you can mix numerical and string enums } const FruitEnum = z.nativeEnum(Fruits); type FruitEnum = z.infer; // 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+! ```ts const Fruits = { Apple: "apple", Banana: "banana", Cantaloupe: 3, } as const; const FruitEnum = z.nativeEnum(Fruits); type FruitEnum = z.infer; // "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: ```ts 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. ```ts const schema = z.optional(z.string()); schema.parse(undefined); // => returns undefined type A = z.infer; // string | undefined ``` For convenience, you can also call the `.optional()` method on an existing schema. ```ts const user = z.object({ username: z.string().optional(), }); type C = z.infer; // { username?: string | undefined }; ``` You can extract the wrapped schema from a `ZodOptional` instance with `.unwrap()`. ```ts const stringSchema = z.string(); const optionalString = stringSchema.optional(); optionalString.unwrap() === stringSchema; // true ``` ## Nullables Similarly, you can create nullable types with `z.nullable()`. ```ts const nullableString = z.nullable(z.string()); nullableString.parse("asdf"); // => "asdf" nullableString.parse(null); // => null ``` Or use the `.nullable()` method. ```ts const E = z.string().nullable(); // equivalent to nullableString type E = z.infer; // string | null ``` Extract the inner schema with `.unwrap()`. ```ts const stringSchema = z.string(); const nullableString = stringSchema.nullable(); nullableString.unwrap() === stringSchema; // true ``` ## Objects ```ts // 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; // equivalent to: type Dog = { name: string; age: number; }; ``` ### `.shape` Use `.shape` to access the schemas for a particular key. ```ts Dog.shape.name; // => string schema Dog.shape.age; // => number schema ``` ### `.keyof` Use `.keyof` to create a `ZodEnum` schema from the keys of an object schema. ```ts const keySchema = Dog.keyof(); keySchema; // ZodEnum<["name", "age"]> ``` ### `.extend` You can add additional fields to an object schema with the `.extend` method. ```ts const DogWithBreed = Dog.extend({ breed: z.string(), }); ``` You can use `.extend` to overwrite fields! Be careful with this power! ### `.merge` Equivalent to `A.extend(B.shape)`. ```ts 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; // => { students: string[], id: string } ``` > If the two schemas share keys, the properties of B overrides the property of A. The returned schema also inherits the "unknownKeys" policy (strip/strict/passthrough) and the catchall schema of B. ### `.pick/.omit` Inspired by TypeScript's built-in `Pick` and `Omit` utility types, all Zod object schemas have `.pick` and `.omit` methods that return a modified version. Consider this Recipe schema: ```ts const Recipe = z.object({ id: z.string(), name: z.string(), ingredients: z.array(z.string()), }); ``` To only keep certain keys, use `.pick` . ```ts const JustTheName = Recipe.pick({ name: true }); type JustTheName = z.infer; // => { name: string } ``` To remove certain keys, use `.omit` . ```ts const NoIDRecipe = Recipe.omit({ id: true }); type NoIDRecipe = z.infer; // => { name: string, ingredients: string[] } ``` ### `.partial` Inspired by the built-in TypeScript utility type [Partial](https://www.typescriptlang.org/docs/handbook/utility-types.html#partialtype), the `.partial` method makes all properties optional. Starting from this object: ```ts const user = z.object({ email: z.string(), username: z.string(), }); // { email: string; username: string } ``` We can create a partial version: ```ts const partialUser = user.partial(); // { email?: string | undefined; username?: string | undefined } ``` You can also specify which properties to make optional: ```ts const optionalEmail = user.partial({ email: true, }); /* { email?: string | undefined; username: string } */ ``` ### `.deepPartial` The `.partial` method is shallow — it only applies one level deep. There is also a "deep" version: ```ts const user = z.object({ username: z.string(), location: z.object({ latitude: z.number(), longitude: z.number(), }), strings: z.array(z.object({ value: z.string() })), }); const deepPartialUser = user.deepPartial(); /* { username?: string | undefined, location?: { latitude?: number | undefined; longitude?: number | undefined; } | undefined, strings?: { value?: string}[] } */ ``` > Important limitation: deep partials only work as expected in hierarchies of objects, arrays, and tuples. ### `.required` Contrary to the `.partial` method, the `.required` method makes all properties required. Starting from this object: ```ts const user = z .object({ email: z.string(), username: z.string(), }) .partial(); // { email?: string | undefined; username?: string | undefined } ``` We can create a required version: ```ts const requiredUser = user.required(); // { email: string; username: string } ``` You can also specify which properties to make required: ```ts const requiredEmail = user.required({ email: true, }); /* { email: string; username?: string | undefined; } */ ``` ### `.passthrough` By default Zod object schemas strip out unrecognized keys during parsing. ```ts 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()` . ```ts person.passthrough().parse({ name: "bob dylan", extraKey: 61, }); // => { name: "bob dylan", extraKey: 61 } ``` ### `.strict` By default Zod object schemas strip out unrecognized keys during parsing. You can _disallow_ unknown keys with `.strict()` . If there are any unknown keys in the input, Zod will throw an error. ```ts 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. ```ts 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 ```ts 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: ```ts z.string().optional().array(); // (string | undefined)[] z.string().array().optional(); // string[] | undefined ``` ### `.element` Use `.element` to access the schema for an element of the array. ```ts stringArray.element; // => string schema ``` ### `.nonempty` If you want to ensure that an array contains at least one element, use `.nonempty()`. ```ts 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: ```ts // optional custom error message const nonEmptyStrings = z.string().array().nonempty({ message: "Can't be empty!", }); ``` ### `.min/.max/.length` ```ts z.string().array().min(5); // must contain 5 or more items z.string().array().max(5); // must contain 5 or fewer items z.string().array().length(5); // must contain 5 items exactly ``` Unlike `.nonempty()` these methods do not change the inferred type. ## Tuples Unlike arrays, tuples have a fixed number of elements and each element can have a different type. ```ts const athleteSchema = z.tuple([ z.string(), // name z.number(), // jersey number z.object({ pointsScored: z.number(), }), // statistics ]); type Athlete = z.infer; // type Athlete = [string, number, { pointsScored: number }] ``` A variadic ("rest") argument can be added with the `.rest` method. ```ts 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. ```ts 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](#or): ```ts 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](#literals). This example validates an input that is optional but needs to contain a [valid URL](#strings): ```ts 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. ```ts 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". ```ts 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. ```ts myUnion.options; // [ZodObject<...>, ZodObject<...>] ``` To merge two or more discriminated unions, use `.options` with destructuring. ```ts 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`. This is particularly useful for storing or caching items by ID. ```ts const User = z.object({ name: z.string() }); const UserStore = z.record(z.string(), User); type UserStore = z.infer; // => Record ``` The schema and inferred type can be used like so: ```ts 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** While `z.record(keyType, valueType)` is able to accept numerical key types and TypeScript's built-in Record type is `Record`, it's hard to represent the TypeScript type `Record` in Zod. As it turns out, TypeScript's behavior surrounding `[k: number]` is a little unintuitive: ```ts 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 ```ts const stringNumberMap = z.map(z.string(), z.number()); type StringNumberMap = z.infer; // type StringNumberMap = Map ``` ## Sets ```ts const numberSet = z.set(z.number()); type NumberSet = z.infer; // type NumberSet = Set ``` Set schemas can be further constrained with the following utility methods. ```ts z.set(z.string()).nonempty(); // must contain at least one item z.set(z.string()).min(5); // must contain 5 or more items z.set(z.string()).max(5); // must contain 5 or fewer items z.set(z.string()).size(5); // must contain 5 items exactly ``` ## Intersections Intersections are useful for creating "logical AND" types. This is useful for intersecting two object types. ```ts 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`. ```ts 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; // => 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". ```ts const baseCategorySchema = z.object({ name: z.string(), }); type Category = z.infer & { subcategories: Category[]; }; const categorySchema: z.ZodType = baseCategorySchema.extend({ subcategories: z.lazy(() => categorySchema.array()), }); categorySchema.parse({ name: "People", subcategories: [ { name: "Politicians", subcategories: [ { name: "Presidents", subcategories: [], }, ], }, ], }); // passes ``` Thanks to [crasite](https://github.com/crasite) for this example. ### ZodType with ZodEffects When using `z.ZodType` with `z.ZodEffects` ( [`.refine`](https://github.com/colinhacks/zod#refine), [`.transform`](https://github.com/colinhacks/zod#transform), [`preprocess`](https://github.com/colinhacks/zod#preprocess), etc... ), you will need to define the input and output types of the schema. `z.ZodType` ```ts const isValidId = (id: string): id is `${string}/${string}` => id.split("/").length === 2; const baseSchema = z.object({ id: z.string().refine(isValidId), }); type Input = z.input & { children: Input[]; }; type Output = z.output & { children: Output[]; }; const schema: z.ZodType = baseSchema.extend({ children: z.lazy(() => schema.array()), }); ``` Thanks to [marcus13371337](https://github.com/marcus13371337) and [JoelBeeldi](https://github.com/JoelBeeldi) for this example. ### JSON type If you want to validate any JSON value, you can use the snippet below. ```ts const literalSchema = z.union([z.string(), z.number(), z.boolean(), z.null()]); type Literal = z.infer; type Json = Literal | { [key: string]: Json } | Json[]; const jsonSchema: z.ZodType = z.lazy(() => z.union([literalSchema, z.array(jsonSchema), z.record(jsonSchema)]) ); jsonSchema.parse(data); ``` Thanks to [ggoodman](https://github.com/ggoodman) for suggesting this. ### Cyclical objects Despite supporting recursive schemas, passing cyclical data into Zod will cause an infinite loop in some cases. > To detect cyclical objects before they cause problems, consider [this approach](https://gist.github.com/colinhacks/d35825e505e635df27cc950776c5500b). ## Promises ```ts const numberPromise = z.promise(z.number()); ``` "Parsing" works a little differently with promise schemas. Validation happens in two parts: 1. Zod synchronously checks that the input is an instance of Promise (i.e. an object with `.then` and `.catch` methods.). 2. Zod uses `.then` to attach an additional validation step onto the existing Promise. You'll have to use `.catch` on the returned Promise to handle validation failures. ```ts numberPromise.parse("tuna"); // ZodError: Non-Promise type: string numberPromise.parse(Promise.resolve("tuna")); // => Promise 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. ```ts 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)` . ```ts const myFunction = z.function(); type myFunction = z.infer; // => ()=>unknown ``` Define inputs and outputs. ```ts const myFunction = z .function() .args(z.string(), z.number()) // accepts an arbitrary number of arguments .returns(z.boolean()); type myFunction = z.infer; // => (arg0: string, arg1: number)=>boolean ``` Function schemas have an `.implement()` method which accepts a function and returns a new function that automatically validates its inputs and outputs. ```ts 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, just don't call the `.returns()` method. The output type will be inferred from the implementation. > You can use the special `z.void()` option if your function doesn't return anything. This will let Zod properly infer the type of void-returning functions. (Void-returning functions actually return undefined.) ```ts const myFunction = z .function() .args(z.string()) .implement((arg) => { return [arg.length]; }); myFunction; // (arg: string)=>number[] ``` Extract the input and output schemas from a function schema. ```ts myFunction.parameters(); // => ZodTuple<[ZodString, ZodNumber]> myFunction.returnType(); // => ZodBoolean ``` ## Preprocess > Zod now supports primitive coercion without the need for `.preprocess()`. See the [coercion docs](#coercion-for-primitives) 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](#transform).) 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()`. ```ts 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. ```ts const px = z.custom<`${number}px`>((val) => { return typeof val === "string" ? /^\d+px$/.test(val) : false; }); type px = z.infer; // `${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! ```ts 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`](#refine). ```ts 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. ```ts const stringSchema = z.string(); stringSchema.parse("fish"); // => returns "fish" stringSchema.parse(12); // throws error ``` ### `.parseAsync` `.parseAsync(data:unknown): Promise` If you use asynchronous [refinements](#refine) or [transforms](#transform) (more on those later), you'll need to use `.parseAsync`. ```ts 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. ```ts 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: ```ts 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`. ```ts await stringSchema.safeParseAsync("billie"); ``` For convenience, this has been aliased to `.spa`: ```ts 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`](#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` : ```ts const myString = z.string().refine((val) => val.length <= 255, { message: "String can't be more than 255 characters", }); ``` > ⚠️ Refinement functions should not throw. Instead they should return a falsy value to signal failure. #### Arguments As you can see, `.refine` takes two arguments. 1. The first is the validation function. This function takes one input (of type `T` — the inferred type of the schema) and returns `any`. Any truthy value will pass validation. (Prior to zod@1.6.2 the validation function had to return a boolean.) 2. The second argument accepts some options. You can use this to customize certain error-handling behavior: ```ts 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`. ```ts const longString = z.string().refine( (val) => val.length > 10, (val) => ({ message: `${val} is not more than 10 characters` }) ); ``` #### Customize error path ```ts const passwordForm = z .object({ password: z.string(), confirm: z.string(), }) .refine((data) => data.password === data.confirm, { message: "Passwords don't match", path: ["confirm"], // path of error }); passwordForm.parse({ password: "asdf", confirm: "qwer" }); ``` Because you provided a `path` parameter, the resulting error will be: ```ts ZodError { issues: [{ "code": "custom", "path": [ "confirm" ], "message": "Passwords don't match" }] } ``` #### Asynchronous refinements Refinements can also be async: ```ts const userId = z.string().refine(async (id) => { // verify that ID exists in database return true; }); ``` > ⚠️ If you use async refine

	Stars	Issues	Version	Updated	Created
ajv	13,415	321	8.13.0	9 days ago	9 years ago
joi			17.13.1	7 days ago	12 years ago
runtypes	2,548	71	6.7.0	a year ago	8 years ago
v8n	4,161	3	1.5.1	2 years ago	6 years ago
yup	22,274	221	1.4.0	2 months ago	10 years ago
zod	30,597	296	3.23.7	a day ago	4 years ago

ajv vs joi vs runtypes vs v8n vs yup vs zod

Downloads in past1 Month3 Months6 Months1 Year2 Years5 YearsAll time

Stats

Popular Searches

Sick of boring JavaScript newsletters?

Downloads in past