Type validation libraries are essential tools in web development that help ensure data integrity by validating the shape and type of data structures. They are particularly useful in TypeScript environments where type safety is a priority. These libraries provide mechanisms to define schemas, validate data against those schemas, and generate runtime type checks, which can prevent runtime errors and improve overall application robustness. Each library has its unique features and design philosophies, catering to different developer needs and preferences.
Package Weekly Downloads Trend
Github Stars Ranking
Stat Detail
Package
Downloads
Stars
Size
Issues
Publish
License
zod
18,828,181
35,601
699 kB
540
7 days ago
MIT
joi
11,328,010
21,044
531 kB
185
8 months ago
BSD-3-Clause
io-ts
1,995,596
6,741
460 kB
163
2 months ago
MIT
runtypes
238,619
2,631
312 kB
18
13 days ago
MIT
Feature Comparison: zod vs joi vs io-ts vs runtypes
Type Safety
zod:
Zod is designed with TypeScript in mind, providing excellent type inference and ensuring that schemas are type-safe. It allows developers to define schemas that are automatically inferred as TypeScript types, promoting type safety.
joi:
Joi offers a robust validation framework but does not provide type inference directly. It is primarily focused on validating data structures and ensuring they meet specified criteria, making it less type-safe compared to io-ts and Zod.
io-ts:
io-ts provides strong type inference capabilities, allowing developers to define complex types that are validated at runtime. It leverages TypeScript's type system to ensure that the data conforms to the expected structure, enhancing type safety throughout the application.
runtypes:
runtypes focuses on runtime type checking and provides a simple way to define types that can be validated at runtime. It integrates well with TypeScript, allowing developers to enforce type safety without much overhead.
Ease of Use
zod:
Zod is designed for simplicity and ease of use, with a clean and intuitive syntax. It allows developers to define schemas quickly, making it a great choice for rapid development.
joi:
Joi is known for its user-friendly API and fluent syntax, making it easy to define complex validation rules. Developers can quickly write and understand validation schemas, which enhances productivity.
io-ts:
io-ts has a steeper learning curve due to its functional programming approach and the need to understand its type combinators. However, once mastered, it offers powerful capabilities for type validation.
runtypes:
runtypes has a straightforward API that is easy to grasp, making it accessible for developers who want to implement runtime type checking without extensive setup or configuration.
Performance
zod:
Zod is optimized for performance and is designed to be fast, making it suitable for applications that require frequent validation without compromising speed.
joi:
Joi is generally performant but may experience slowdowns with very complex validation schemas. It is well-optimized for typical use cases, especially in server-side applications.
io-ts:
io-ts can introduce some overhead due to its functional programming nature and the complexity of its type checks. However, it is optimized for performance and can handle large data structures efficiently when used correctly.
runtypes:
runtypes is lightweight and designed for performance, making it suitable for applications where runtime type checking is critical without significant overhead.
Extensibility
zod:
Zod supports extensibility through custom validators and schema compositions, allowing developers to create complex validation logic while maintaining simplicity.
joi:
Joi provides a rich set of built-in validators and allows for custom validation functions, making it highly extensible for various use cases. Developers can easily create reusable validation schemas.
io-ts:
io-ts is highly extensible, allowing developers to create custom types and validation logic easily. This flexibility makes it suitable for complex applications with unique validation requirements.
runtypes:
runtypes offers basic extensibility but is more focused on simplicity. It allows for custom type definitions but may not be as feature-rich as Joi or io-ts in this regard.
Community and Support
zod:
Zod is rapidly growing in popularity, especially among TypeScript developers. It has a supportive community and good documentation, making it easier for newcomers to adopt.
joi:
Joi has a large and active community, with extensive documentation and numerous resources available. This support makes it easier for developers to find solutions and examples for their validation needs.
io-ts:
io-ts has a smaller community compared to Joi but is well-supported within the TypeScript ecosystem. Its documentation is thorough, aiding developers in understanding its concepts.
runtypes:
runtypes has a smaller community but is gaining traction among TypeScript users. Its documentation is clear, but the community support may not be as extensive as Joi or Zod.
How to Choose: zod vs joi vs io-ts vs runtypes
zod:
Choose Zod if you want a modern and developer-friendly library that emphasizes simplicity and TypeScript support. Zod provides a concise syntax for schema definitions and is designed for ease of use, making it a great choice for both small and large projects.
joi:
Select Joi if you need a mature and feature-rich validation library that is easy to use and offers a wide range of built-in validators. Joi is well-suited for server-side validation in Node.js applications and provides a fluent API for defining complex validation rules.
io-ts:
Choose io-ts if you are looking for a library that integrates seamlessly with TypeScript and offers powerful type inference capabilities. It is particularly useful for projects that require a strong emphasis on type safety and functional programming paradigms.
runtypes:
Opt for runtypes if you prefer a lightweight library that focuses on runtime type checking with a simple API. It is ideal for projects where you want to enforce type safety without the overhead of more complex libraries, and it works well with TypeScript.
Similar Npm Packages to zod
zod is a TypeScript-first schema declaration and validation library. It allows developers to define schemas for their data structures and validate data against these schemas in a type-safe manner. Zod is particularly useful for ensuring that the data conforms to expected formats, making it a great choice for applications that require robust data validation. While Zod offers a powerful solution for schema validation, there are several alternatives in the ecosystem that provide similar functionalities. Here are a few notable alternatives:
io-ts is a runtime type system for TypeScript that allows you to define types and validate data at runtime. It provides a functional approach to validation and can be integrated with other libraries like fp-ts for functional programming paradigms. io-ts is particularly useful for applications that require both static type checking and runtime validation, making it a solid choice for developers who prioritize functional programming principles.
joi is a powerful schema description language and data validator for JavaScript objects. It provides a rich set of features for defining complex validation rules and is widely used in Node.js applications. Joi's expressive syntax allows developers to create detailed validation schemas with ease. If you are looking for a mature and feature-rich validation library that works well in both client-side and server-side applications, joi is an excellent option.
yup is a JavaScript schema builder for value parsing and validation. It is heavily inspired by Joi but is designed to work seamlessly with React and other modern JavaScript frameworks. Yup provides a simple and intuitive API for defining validation schemas and supports asynchronous validation. If you are building applications with React and need a validation library that integrates well with form libraries like Formik, yup is a great choice.
joi is a powerful schema description language and data validator for JavaScript objects. It allows developers to define complex validation rules for their data structures, making it easier to ensure that incoming data meets specific criteria before processing it. Joi is particularly useful in server-side applications, where data validation is crucial for maintaining data integrity and security. While joi is a popular choice for data validation, there are several alternatives available in the ecosystem. Here are a few notable ones:
celebrate is a middleware for Express.js that integrates Joi for validating request data. It allows developers to define validation schemas for request parameters, query strings, and request bodies, making it easy to enforce data integrity in Express applications. Celebrate simplifies the validation process by providing a straightforward API that works seamlessly with Express, ensuring that only valid data reaches your route handlers. If you're already using Joi and want to integrate it into your Express application, Celebrate is an excellent choice.
express-validator is another popular middleware for validating and sanitizing request data in Express applications. Unlike Joi, which focuses on schema-based validation, express-validator uses a set of validation and sanitization middlewares that can be applied to individual routes. This flexibility allows developers to define validation rules directly in their route definitions. If you prefer a more modular approach to validation and want to keep your validation logic close to your route handlers, express-validator is a great alternative.
yup is a JavaScript schema builder for value parsing and validation. It is similar to Joi but offers a more modern API and is often favored for its promise-based validation and support for asynchronous validation. Yup is particularly useful for client-side validation in React applications, but it can also be used in server-side contexts. If you're looking for a lightweight and flexible validation library that works well with both client and server applications, Yup is worth considering.
io-ts is a TypeScript library for runtime type validation and decoding. It allows developers to define types using a functional approach and validate data at runtime, ensuring that the data conforms to the specified types. This is particularly useful in scenarios where data comes from external sources, such as APIs, and needs to be validated before use. io-ts integrates seamlessly with TypeScript, providing strong type inference and ensuring type safety throughout your application.
While io-ts offers a robust solution for runtime type validation, there are several alternatives in the ecosystem that also provide similar functionality. Here are a few noteworthy options:
joi is a powerful schema description language and data validator for JavaScript objects. It allows developers to create complex validation rules and provides a rich set of features for validating and sanitizing data. joi is widely used in Node.js applications and is known for its expressive syntax and flexibility. If you are looking for a comprehensive validation library that can handle complex validation scenarios, joi is an excellent choice.
runtypes is a library for creating runtime type checkers in TypeScript. It allows developers to define types and validate data against those types at runtime. runtypes is designed to be simple and lightweight, making it easy to integrate into existing TypeScript projects. If you prefer a minimalistic approach to runtime type validation while still leveraging TypeScript's type system, runtypes is worth considering.
zod is a TypeScript-first schema declaration and validation library. It provides a simple and intuitive API for defining schemas and validating data, with a strong focus on TypeScript support. zod allows developers to create complex validation rules while maintaining type safety, making it a great choice for TypeScript applications. If you want a library that is easy to use and integrates well with TypeScript, zod is a strong contender.
runtypes is a TypeScript library designed for runtime type checking. It allows developers to define and validate the structure of data at runtime, ensuring that the data conforms to the expected types. This is particularly useful in scenarios where data is received from external sources, such as APIs, and helps catch errors early in the development process. While runtypes offers a robust solution for type validation, there are several alternatives in the ecosystem that provide similar functionality. Here are a few notable alternatives:
io-ts is a runtime type system for IO decoding and validation in TypeScript. It allows developers to define complex types and validate data against those types at runtime. With its functional programming approach, io-ts provides a powerful way to handle type validation, including support for union types, intersection types, and more. If you are looking for a library that integrates well with functional programming paradigms and offers extensive type validation capabilities, io-ts is a strong candidate.
joi is a popular schema description language and data validator for JavaScript. It provides a rich set of features for defining complex validation rules and is widely used in Node.js applications. joi allows developers to create schemas that can validate various data types, including objects, arrays, and strings. If you need a comprehensive validation library with a mature ecosystem and extensive documentation, joi is an excellent choice.
superstruct is a simple and composable way to validate data in JavaScript and TypeScript. It allows developers to define structures and validate data against those structures using a straightforward API. superstruct is lightweight and easy to use, making it a great option for projects that require basic validation without the overhead of more complex libraries.
yup is a JavaScript schema builder for value parsing and validation. It is particularly popular in the React ecosystem, especially when used with form libraries like Formik. yup provides a fluent API for defining schemas and supports asynchronous validation, making it a versatile choice for handling form validation in web applications.
zod is a TypeScript-first schema declaration and validation library. It is designed to be simple and intuitive, allowing developers to define schemas using a straightforward syntax. zod is particularly useful for TypeScript users who want to leverage type inference and ensure that their data structures are validated at runtime.
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
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.
zod-endpoints: Contract-first strictly typed endpoints with Zod. OpenAPI compatible.
zhttp: An OpenAPI compatible, strictly typed http library with Zod input and response validation.
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: A typescript API client with runtime and compile time validation backed by axios and zod.
express-zod-api: Build Express-based APIs with I/O schema validation and custom middlewares.
tapiduck: End-to-end typesafe JSON APIs with Zod and Express; a bit like tRPC, but simpler.
koa-zod-router: Create typesafe routes in Koa with I/O validation using Zod.
zod-sockets: Zod-powered Socket.IO microframework with I/O validation and built-in AsyncAPI specs
oas-tszod-gen: Client SDK code generator to convert OpenApi v3 specifications into TS endpoint caller functions with Zod types.
Form integrations
react-hook-form: A first-party Zod resolver for React Hook Form.
pastel: Create CLI applications with react, zod, and ink.
zod-xlsx: A xlsx based resource validator using Zod schemas.
znv: Type-safe environment parsing and validation for Node.js with Zod schemas.
zod-config: Load configurations across multiple sources with flexible adapters, ensuring type safety with Zod.
unplugin-environment: A plugin for loading enviroment variables safely with schema validation, simple with virtual module, type-safe with intellisense, and better DX 🔥 🚀 👷. Powered by Zod.
zod-struct: Create runtime-checked structs with Zod.
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.
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.
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().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
z.string().cidr(); // 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 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" });
z.string().cidr({ message: "Invalid CIDR" });
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.
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.
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.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.
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().
// all properties are required by default
const Dog = z.object({
name: z.string(),
age: z.number(),
});
// extract the inferred type like this
type Dog = z.infer<typeof Dog>;
// equivalent to:
type Dog = {
name: string;
age: number;
};
.shape
Use .shape to access the schemas for a particular key.
Dog.shape.name; // => string schema
Dog.shape.age; // => number schema
.keyof
Use .keyof to create a ZodEnum schema from the keys of an object schema.
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:
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.
const person = z
.object({
name: z.string(),
})
.strict();
person.parse({
name: "bob dylan",
extraKey: 61,
});
// => throws ZodError
.strip
You can use the .strip method to reset an object schema to the default behavior (stripping unrecognized keys).
.catchall
You can pass a "catchall" schema into an object schema. All unknown keys will be validated against it.
const person = z
.object({
name: z.string(),
})
.catchall(z.number());
person.parse({
name: "bob dylan",
validExtraKey: 61, // works fine
});
person.parse({
name: "bob dylan",
validExtraKey: false, // fails
});
// => throws ZodError
Using .catchall() obviates .passthrough() , .strip() , or .strict(). All keys are now considered "known".
Use .element to access the schema for an element of the array.
stringArray.element; // => string schema
.nonempty
If you want to ensure that an array contains at least one element, use .nonempty().
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:
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.
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.
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".
While z.record(keyType, valueType) is able to accept numerical key types and TypeScript's built-in Record type is Record<KeyType, ValueType>, it's hard to represent the TypeScript type Record<number, any> in Zod.
As it turns out, TypeScript's behavior surrounding [k: number] is a little unintuitive:
As you can see, JavaScript automatically casts all object keys to strings under the hood. Since Zod is trying to bridge the gap between static and runtime types, it doesn't make sense to provide a way of creating a record schema with numerical keys, since there's no such thing as a numerical key in runtime JavaScript.
Maps
const stringNumberMap = z.map(z.string(), z.number());
type StringNumberMap = z.infer<typeof stringNumberMap>;
// type StringNumberMap = Map<string, number>
Sets
const numberSet = z.set(z.number());
type NumberSet = z.infer<typeof numberSet>;
// type NumberSet = Set<number>
Set schemas can be further constrained with the following utility methods.
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.
Though in many cases, it is recommended to use A.merge(B) to merge two objects. The .merge method returns a new ZodObject instance, whereas A.and(B) returns a less useful ZodIntersection instance that lacks common object methods like pick and omit.
const a = z.union([z.number(), z.string()]);
const b = z.union([z.number(), z.boolean()]);
const c = z.intersection(a, b);
type c = z.infer<typeof c>; // => number
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".
When using z.ZodType with z.ZodEffects (
.refine,
.transform,
preprocess,
etc...
), you will need to define the input and output types of the schema. z.ZodType<Output, z.ZodTypeDef, Input>
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.
Promises
const numberPromise = z.promise(z.number());
"Parsing" works a little differently with promise schemas. Validation happens in two parts:
Zod synchronously checks that the input is an instance of Promise (i.e. an object with .then and .catch methods.).
Zod uses .then to attach an additional validation step onto the existing Promise. You'll have to use .catch on the returned Promise to handle validation failures.
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()
.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
Function schemas have an .implement() method which accepts a function and returns a new function that automatically validates its inputs and outputs.
const trimmedLength = z
.function()
.args(z.string()) // accepts an arbitrary number of arguments
.returns(z.number())
.implement((x) => {
// TypeScript knows x is a string!
return x.trim().length;
});
trimmedLength("sandwich"); // => 8
trimmedLength(" asdf "); // => 4
If you only care about validating inputs, 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.)
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().
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.
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.
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.
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.
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` })
);
You can add as many issues as you like. If ctx.addIssue is not called during the execution of the function, validation passes.
Normally refinements always create issues with a ZodIssueCode.custom error code, but with superRefine it's possible to throw issues of any ZodIssueCode. Each issue code is described in detail in the Error Handling guide: ERROR_HANDLING.md.
Abort early
By default, parsing will continue even after a refinement check fails. For instance, if you chain together multiple refinements, they will all be executed. However, it may be desirable to abort early to prevent later refinements from being executed. To achieve this, pass the fatal flag to ctx.addIssue and return z.NEVER.
If you provide a type predicate to .refine() or .superRefine(), the resulting type will be narrowed down to your predicate's type. This is useful if you are mixing multiple chained refinements and transformations:
const schema = z
.object({
first: z.string(),
second: z.number(),
})
.nullable()
.superRefine((arg, ctx): arg is { first: string; second: number } => {
if (!arg) {
ctx.addIssue({
code: z.ZodIssueCode.custom, // customize your issue
message: "object should exist",
});
}
return z.NEVER; // The return value is not used, but we need to return something to satisfy the typing
})
// here, TS knows that arg is not null
.refine((arg) => arg.first === "bob", "`first` is not `bob`!");
⚠️ You must use ctx.addIssue() instead of returning a boolean value to indicate whether the validation passes. If ctx.addIssue is not called during the execution of the function, validation passes.
.transform
To transform data after parsing, use the transform method.
Note that stringToNumber above is an instance of the ZodEffects subclass. It is NOT an instance of ZodString. If you want to use the built-in methods of ZodString (e.g. .email()) you must apply those methods before any transforms.
The .transform method can simultaneously validate and transform the value. This is often simpler and less duplicative than chaining transform and refine.
As with .superRefine, the transform function receives a ctx object with an addIssue method that can be used to register validation issues.
const numberInString = z.string().transform((val, ctx) => {
const parsed = parseInt(val);
if (isNaN(parsed)) {
ctx.addIssue({
code: z.ZodIssueCode.custom,
message: "Not a number",
});
// This is a special symbol you can use to
// return early from the transform function.
// It has type `never` so it does not affect the
// inferred return type.
return z.NEVER;
}
return parsed;
});
Relationship to refinements
Transforms and refinements can be interleaved. These will be executed in the order they are declared.
Conceptually, this is how Zod processes default values:
If the input is undefined, the default value is returned
Otherwise, the data is parsed using the base schema
.describe
Use .describe() to add a description property to the resulting schema.
const documentedString = z
.string()
.describe("A useful bit of text, if you know what to do with it.");
documentedString.description; // A useful bit of text…
This can be useful for documenting a field, for example in a JSON Schema using a library like zod-to-json-schema).
.catch
Use .catch() to provide a "catch value" to be returned in the event of a parsing error.
Optionally, you can pass a function into .catch that will be re-executed whenever a default value needs to be generated. A ctx object containing the caught error will be passed into this function.
A convenience method that returns a "nullish" version of a schema. Nullish schemas will accept both undefined and null. Read more about the concept of "nullish" in the TypeScript 3.7 release notes.
TypeScript's type system is structural, which means that any two types that are structurally equivalent are considered the same.
type Cat = { name: string };
type Dog = { name: string };
const petCat = (cat: Cat) => {};
const fido: Dog = { name: "fido" };
petCat(fido); // works fine
In some cases, its can be desirable to simulate nominal typing inside TypeScript. For instance, you may wish to write a function that only accepts an input that has been validated by Zod. This can be achieved with branded types (AKA opaque types).
const Cat = z.object({ name: z.string() }).brand<"Cat">();
type Cat = z.infer<typeof Cat>;
const petCat = (cat: Cat) => {};
// this works
const simba = Cat.parse({ name: "simba" });
petCat(simba);
// this doesn't
petCat({ name: "fido" });
Under the hood, this works by attaching a "brand" to the inferred type using an intersection type. This way, plain/unbranded data structures are no longer assignable to the inferred type of the schema.
Note that branded types do not affect the runtime result of .parse. It is a static-only construct.
.readonly
.readonly() => ZodReadonly<this>
This method returns a ZodReadonly schema instance that parses the input using the base schema, then calls Object.freeze() on the result. The inferred type is also marked as readonly.
The .pipe() method returns a ZodPipeline instance.
You can use .pipe() to fix common issues with z.coerce.
You can constrain the input to types that work well with your chosen coercion. Then use .pipe() to apply the coercion.
without constrained input:
const toDate = z.coerce.date();
// works intuitively
console.log(toDate.safeParse("2023-01-01").success); // true
// might not be what you want
console.log(toDate.safeParse(null).success); // true
with constrained input:
const datelike = z.union([z.number(), z.string(), z.date()]);
const datelikeToDate = datelike.pipe(z.coerce.date());
// still works intuitively
console.log(datelikeToDate.safeParse("2023-01-01").success); // true
// more likely what you want
console.log(datelikeToDate.safeParse(null).success); // false
You can also use this technique to avoid coercions that throw uncaught errors.
without constrained input:
const toBigInt = z.coerce.bigint();
// works intuitively
console.log(toBigInt.safeParse("42")); // true
// probably not what you want
console.log(toBigInt.safeParse(null)); // throws uncaught error
with constrained input:
const toNumber = z.number().or(z.string()).pipe(z.coerce.number());
const toBigInt = z.bigint().or(toNumber).pipe(z.coerce.bigint());
// still works intuitively
console.log(toBigInt.safeParse("42").success); // true
// error handled by zod, more likely what you want
console.log(toBigInt.safeParse(null).success); // false
Guides and concepts
Type inference
You can extract the TypeScript type of any schema with z.infer<typeof mySchema> .
const A = z.string();
type A = z.infer<typeof A>; // string
const u: A = 12; // TypeError
const u: A = "asdf"; // compiles
What about transforms?
In reality each Zod schema internally tracks two types: an input and an output. For most schemas (e.g. z.string()) these two are the same. But once you add transforms into the mix, these two values can diverge. For instance z.string().transform(val => val.length) has an input of string and an output of number.
You can separately extract the input and output types like so:
const stringToNumber = z.string().transform((val) => val.length);
// ⚠️ Important: z.infer returns the OUTPUT type!
type input = z.input<typeof stringToNumber>; // string
type output = z.output<typeof stringToNumber>; // number
// equivalent to z.output!
type inferred = z.infer<typeof stringToNumber>; // number
Writing generic functions
With TypeScript generics, you can write reusable functions that accept Zod schemas as parameters. This enables you to create custom validation logic, schema transformations, and more, while maintaining type safety and inference.
When attempting to write a function that accepts a Zod schema as an input, it's tempting to try something like this:
function inferSchema<T>(schema: z.ZodType<T>) {
return schema;
}
This approach is incorrect, and limits TypeScript's ability to properly infer the argument. No matter what you pass in, the type of schema will be an instance of ZodType.
inferSchema(z.string());
// => ZodType<string>
This approach loses type information, namely which subclass the input actually is (in this case, ZodString). That means you can't call any string-specific methods like .min() on the result of inferSchema.
A better approach is to infer the schema as a whole instead of merely its inferred type. You can do this with a utility type called z.ZodTypeAny.
ZodTypeAny is just a shorthand for ZodType<any, any, any>, a type that is broad enough to match any Zod schema.
The Result is now fully and properly typed, and the type system can infer the specific subclass of the schema.
Inferring the inferred type
If you follow the best practice of using z.ZodTypeAny as the generic parameter for your schema, you may encounter issues with the parsed data being typed as any instead of the inferred type of the schema.
function parseData<T extends z.ZodTypeAny>(data: unknown, schema: T) {
return schema.parse(data);
}
parseData("sup", z.string());
// => any
Due to how TypeScript inference works, it is treating schema like a ZodTypeAny instead of the inferred type. You can fix this with a type cast using z.infer.
function parseData<T extends z.ZodTypeAny>(data: unknown, schema: T) {
return schema.parse(data) as z.infer<T>;
// ^^^^^^^^^^^^^^ <- add this
}
parseData("sup", z.string());
// => string
By constraining these in your generic input, you can limit what schemas are allowable as inputs to your function:
function makeSchemaOptional<T extends z.ZodType<string>>(schema: T) {
return schema.optional();
}
makeSchemaOptional(z.string());
// works fine
makeSchemaOptional(z.number());
// Error: 'ZodNumber' is not assignable to parameter of type 'ZodType<string, ZodTypeDef, string>'
Error handling
Zod provides a subclass of Error called ZodError. ZodErrors contain an issues array containing detailed information about the validation problems.
const result = z
.object({
name: z.string(),
})
.safeParse({ name: 12 });
if (!result.success) {
result.error.issues;
/* [
{
"code": "invalid_type",
"expected": "string",
"received": "number",
"path": [ "name" ],
"message": "Expected string, received number"
}
] */
}
For detailed information about the possible error codes and how to customize error messages, check out the dedicated error handling guide: ERROR_HANDLING.md
Zod's error reporting emphasizes completeness and correctness. If you are looking to present a useful error message to the end user, you should either override Zod's error messages using an error map (described in detail in the Error Handling guide) or use a third-party library like zod-validation-error
Error formatting
You can use the .format() method to convert this error into a nested object.
const result = z
.object({
name: z.string(),
})
.safeParse({ name: 12 });
if (!result.success) {
const formatted = result.error.format();
/* {
name: { _errors: [ 'Expected string, received number' ] }
} */
formatted.name?._errors;
// => ["Expected string, received number"]
}
Comparison
There are a handful of other widely-used validation libraries, but all of them have certain design limitations that make for a non-ideal developer experience.
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
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.