TypeScript-first schema declaration and validation library with static type inference
Zod is a TypeScript-first schema declaration and validation library. It allows developers to create complex schemas for data validation with a simple and intuitive API. Zod schemas are composable and can be used to validate data at the edge of your application, ensuring that you're working with well-structured and type-safe data.
Basic Type Validation
Validates that the input is a string.
{"const schema = zod.string(); try { schema.parse('hello world'); } catch (e) { console.error(e); }"}Object Schema Validation
Validates that the input is an object with specific properties of certain types.
{"const userSchema = zod.object({ name: zod.string(), age: zod.number(), email: zod.string().email() }); try { userSchema.parse({ name: 'John', age: 30, email: 'john@example.com' }); } catch (e) { console.error(e); }"}Array Validation
Validates that the input is an array of strings.
{"const stringArraySchema = zod.array(zod.string()); try { stringArraySchema.parse(['apple', 'banana']); } catch (e) { console.error(e); }"}Complex Nested Validation
Validates nested objects with various property types.
{"const nestedSchema = zod.object({ user: zod.object({ name: zod.string(), contact: zod.object({ email: zod.string().email(), phone: zod.string() }) }) }); try { nestedSchema.parse({ user: { name: 'Jane', contact: { email: 'jane@example.com', phone: '123-456-7890' } } }); } catch (e) { console.error(e); }"}Custom Validation
Validates that a number is positive using custom validation logic.
{"const positiveNumber = zod.number().positive(); try { positiveNumber.parse(42); } catch (e) { console.error(e); }"}Error Formatting
Formats validation errors for easier debugging and display.
{"const schema = zod.string(); try { schema.parse(42); } catch (e) { console.error(e.format()); }"}Joi is a powerful schema description language and data validator for JavaScript. It offers a similar API to Zod but has been around longer and is often considered more mature. Joi provides a wide range of built-in validators and is highly extensible.
Yup is a JavaScript schema builder for value parsing and validation. It defines a schema with an expressive API and can be used with or without TypeScript. Yup is often used in the context of form validation, especially with libraries like Formik.
Ajv is a JSON Schema Validator. It validates data against JSON Schema (draft 06/07/2019) and is known for its performance. Unlike Zod, which is TypeScript-first, Ajv focuses on JSON Schema validation and is often used for validating data structures in RESTful APIs.
Class-validator allows for validation of class instances based on decorators. It is tightly coupled with TypeScript and uses decorators to define validation rules, which can be more familiar to developers used to working with TypeScript classes and decorators.
Created and maintained by @vriad. The motivation for this library and a detailed comparison to various alternatives can be found at https://vriad.com/blog/zod.
If you find this package useful, leave a star to help more folks find it āļøš¤
To install the latest version:
npm install --save zod
yarn add zod
Zod 1.0.x is compatible with TypeScript 3.2+.
Zod is a validation library designed for optimal developer experience. It's a TypeScript-first schema declaration library with rigorous (and correct!) inferred types, incredible developer experience, and a few killer features missing from the existing libraries.
Zod was also designed with some core principles designed to make all declarations as non-magical and developer-friendly as possible:
.optional() return a new instance.import * as z from 'zod';
const stringSchema = z.string(); // => ZodType<string>
const numberSchema = z.number(); // => ZodType<number>
const booleanSchema = z.boolean(); // => ZodType<boolean>
const dateSchema = z.date(); // => ZodType<Date>
const undefinedSchema = z.undefined(); // => ZodType<undefined>
const nullTypeSchema = z.null(); // => ZodType<null>
const tuna = z.literal('tuna'); // => ZodType<'tuna'>
const twelve = z.literal(12); // => ZodType<12>
const tru = z.literal(true); // => ZodType<true>
Currently there is no support for Date literals in Zod. If you have a use case for this feature, please file an issue.
Given a Zod schema, you can call its .parse(data) method to check data is valid. If it is, a value is returned with full type information! Otherwise, an error is thrown.
IMPORTANT: The variable you pass into .parse is not the same variable you get back out. Assuming the value passes validation, you get back a deep clone of the object you passed in.
const stringSchema = z.string();
stringSchema.parse('fish'); // => "fish"
stringSchema.parse(12); // throws Error('Non-string type: number');
You can also use a Zod schema as a type guard using the schema's .check() method, like so:
const stringSchema = z.string();
const blob: any = 'Albuquerque';
if (stringSchema.check(blob)) {
// blob is now of type `string`
// within this if statement
}
You can use the same method to check for invalid data:
const stringSchema = z.string();
const process = (blob: any) => {
if (!stringSchema.check(blob)) {
throw new Error('Not a string');
}
// blob is now of type `string`
// underneath the if statement
};
To learn more about error handling with Zod, jump to Errors.
You can extract the TypeScript type of any schema with z.infer<typeof [schema]>.
const A = z.string();
type A = z.infer<typeof A>; // string
const u: A = 12; // TypeError
const u: A = 'asdf'; // compiles
We'll include examples of inferred types throughout the rest of the documentation.
// all properties are required by default
const dogSchema = z.object({
name: z.string(),
neutered: z.boolean(),
});
type Dog = z.infer<typeof dogSchema>;
/*
equivalent to:
type Dog = {
name:string;
neutered: boolean;
}
*/
const cujo = dogSchema.parse({
name: 'Cujo',
neutered: true,
}); // passes, returns Dog
const fido: Dog = {
name: 'Fido',
}; // TypeError: missing required property `neutered`
.shape propertyconst Location = z.shape({ latitude: z.number(), longitude: z.number() });
const Business = z.shape({
location: Location,
});
Business.shape.location; // => Location schema
You can combine two object schemas with .merge, like so:
const BaseTeacher = z.object({ subjects: z.array(z.string()) });
const HasID = z.object({ id: z.string() });
const Teacher = BaseTeacher.merge(HasId);
type Teacher = z.infer<typeof Teacher>; // => { subjects: string[], id: string }
You're able to fluently chain together many .merge calls as well:
// chaining mixins
const Teacher = BaseTeacher.merge(HasId)
.merge(HasName)
.merge(HasAddress);
.merge is just syntactic sugar over the more generic z.intersection which is documented below.
IMPORTANT: the schema returned by .merge is the intersection of the two schemas. The schema passed into .merge does not "overwrite" properties of the original schema. To demonstrate:
const Obj1 = z.object({ field: z.string() });
const Obj2 = z.object({ field: z.number() });
const Merged = Obj1.merge(Obj2);
type Merged = z.infer<typeof merged>;
// => { field: never }
// because no type can simultaneously be both a string and a number
To "overwrite" existing keys, use .augment (documented below).
You can augment an object schema with the .augment method.
const Animal = z
.object({
species: z.string(),
})
.augment({
population: z.number(),
});
ā ļø You can use .augment to overwrite fields! Be careful with this power!
// overwrites `species`
const ModifiedAnimal = Animal.augment({
species: z.array(z.string()),
});
// => { population: number, species: string[] }
Object masking is one of Zod's killer features. It lets you create slight variations of your object schemas easily and succinctly.
const Recipe = z.object({
id: z.string(),
name: z.string(),
ingredients: z.array(z.string()),
});
Inspired by TypeScript's built-in Pick and Omit utility types, all Zod object schemas have .pick and .omit methods that return a "masked" version of the schema.
To only keep certain keys, use .pick.
const JustTheName = Recipe.pick({ name: true });
type JustTheName = z.infer<typeof JustTheName>; // => { name: string }
To remove certain keys, use .omit.
const NoIDRecipe = Recipe.omit({ id: true });
type NoIDRecipe = z.infer<typeof NoIDRecipe>; // => { name: string, ingredients: string[] }
This is useful for database logic, where endpoints often accept as input slightly modified versions of your database schemas. For instance, the input to a hypothetical createRecipe endpoint would accept the NoIDRecipe type, since the ID will be generated by your database automatically.
This is a vital feature for implementing typesafe backend logic, yet as far as I know, no other validation library (yup, Joi, io-ts, runtypes, class-validator, ow...) offers similar functionality as of this writing (April 2020). This is one of the must-have features that inspired the creation of Zod.
Inspired by the built-in TypeScript utility type Partial, all Zod object schemas have a .partial method that makes all properties optional.
Starting from this object:
const user = z.object({
username: z.string(),
location: z.object({
latitude: z.number(),
longitude: z.number(),
}),
});
/*
{ username: string, location: { city: number, state: number } }
*/
We can create a partial version:
const partialUser = user.partial(); // => { username?: string | undefined }
/*
{
username?: string | undefined,
location?: {
city: number;
state: number;
} | undefined
}
*/
// equivalent to:
const partialUser = z.object({
username: user.shape.username.optional(),
location: user.shape.location.optional(),
});
Or you can use .deepPartial:
const deepPartialUser = user.deepPartial();
/*
{
username?: string | undefined,
location?: {
latitude?: number | undefined;
longitude?: number | undefined;
} | undefined
}
*/
Important limitation: deep partials only work as expected in hierarchies of object schemas. It also can't be used on recursive schemas currently, since creating a recursive schema requires casting to the generic ZodType type (which doesn't include all the methods of the ZodObject class). Currently an improved version of Zod is under development that will have better support for recursive schemas.
IMPORTANT: By default, Zod object schemas do not allow unknown keys.
dogSchema.parse({
name: 'Spot',
neutered: true,
color: 'brown',
}); // Error(`Unexpected keys in object: 'color'`)
This is an intentional decision to make Zod's behavior consistent with TypeScript. Consider this:
const spot: Dog = {
name: 'Spot',
neutered: true,
color: 'brown',
};
// TypeError: Object literal may only specify known
// properties, and 'color' does not exist in type Dog
TypeScript doesn't allow unknown keys when assigning to an object type, so neither does Zod (by default). If you want to allow this, just call the .nonstrict() method on any object schema:
const dogSchemaNonstrict = dogSchema.nonstrict();
dogSchemaNonstrict.parse({
name: 'Spot',
neutered: true,
color: 'brown',
}); // passes
This change is reflected in the inferred type as well:
type NonstrictDog = z.infer<typeof dogSchemaNonstrict>;
/*
{
name:string;
neutered: boolean;
[k:string]: any;
}
*/
Records are similar to object schemas, but don't enforce a type restriction on the keys. For instance:
const objectSchema = z.object({ name: z.string() });
objectSchema only accepts objects with single key: name. You could use .nonstrict() to create a schema that accepts unknown keys, but that schema won't validated the values associated with those unknown keys.
const nonstrict = objectSchema.nonstrict();
type nonstrict = z.infer<typeof nonstrict>;
// => { name: string, [k:string]: any}
const parsed = nonstrict.parse({ name: 'Serena', bar: ['whatever'] });
parsed.bar; // no type information
But what if you want an object that enforces a schema on all of the values it contains? That's when you would use a record.
const User = z.object({
name: z.string(),
});
const UserStore = z.record(User);
type UserStore = z.infer<typeof UserStore>;
// => { [k: string]: { name: string } }
This is particularly useful for storing or caching items by ID.
const userStore: UserStore = {};
userStore['77d2586b-9e8e-4ecf-8b21-ea7e0530eadd'] = {
name: 'Carlotta',
}; // passes
userStore['77d2586b-9e8e-4ecf-8b21-ea7e0530eadd'] = {
whatever: 'Ice cream sundae',
}; // TypeError
And of course you can call .parse just like any other Zod schema.
UserStore.parse({
user_1328741234: { name: 'James' },
}); // => passes
You may have expected z.record() to accept two arguments, one for the keys and one for the values. After all, TypeScript's built-in Record type does (Record<KeyType, ValueType>)Otherwise, how do you represent the TypeScript type Record<number, any> in Zod?
As it turns out, TypeScript's behavior surrounding [k: number] is a little unintuitive:
const testMap: { [k: number]: string } = {
1: 'one',
};
for (const key in testMap) {
console.log(`${key}: ${typeof key}`);
}
// prints: `1: string`
As you can see, JavaScript automatically casts all object keys to strings under the hood. Since Zod is trying to bridge the gap between static and runtime types, it doesn't make sense to provide a way of creating a record schema with numerical keys, since there's no such thing as a numerical key in runtime JavaScript.
const dogsList = z.array(dogSchema);
dogsList.parse([{ name: 'Fido', age: 4, neutered: true }]); // passes
dogsList.parse([]); // passes
const nonEmptyDogsList = z.array(dogSchema).nonempty();
nonEmptyDogsList.parse([]); // throws Error("Array cannot be empty")
Zod includes a built-in z.union method for composing "OR" types.
const stringOrNumber = z.union([z.string(), z.number()]);
stringOrNumber.parse('foo'); // passes
stringOrNumber.parse(14); // passes
Unions are the basis for defining optional schemas. An "optional string" is just the union of string and undefined.
const A = z.union([z.string(), z.undefined()]);
A.parse(undefined); // => passes, returns undefined
type A = z.infer<typeof A>; // string | undefined
Zod provides a shorthand way to make any schema optional:
const B = z.string().optional(); // equivalent to A
const C = z.object({
username: z.string().optional(),
});
type C = z.infer<typeof C>; // { username?: string | undefined };
Similarly, you can create nullable types like so:
const D = z.union([z.string(), z.null()]);
Or you can use the shorthand .nullable():
const E = z.string().nullable(); // equivalent to D
type E = z.infer<typeof D>; // string | null
You can create unions of any two or more schemas.
/* Custom Union Types */
const F = z
.union([z.string(), z.number(), z.boolean()])
.optional()
.nullable();
F.parse('tuna'); // => tuna
F.parse(42); // => 42
F.parse(true); // => true
F.parse(undefined); // => undefined
F.parse(null); // => null
F.parse({}); // => throws Error!
type F = z.infer<typeof F>; // string | number | boolean | undefined | null;
You can combine unions and string literals to create an enum schemas.
const FishEnum = z.union([z.literal('Salmon'), z.literal('Tuna'), z.literal('Trout')]);
FishEnum.parse('Salmon'); // => "Salmon"
FishEnum.parse('Flounder'); // => throws
You can also use the built-in z.enum() function, like so:
const FishEnum = z.enum(['Salmon', 'Tuna', 'Trout']);
// if you use `z.enum([ ... ])`
// you can also autocomplete enum values
// with the computed `.Values` property
FishEnum.Values.Salmon; // => autocompletes
FishEnum.Values;
/*
=> {
Salmon: "Salmon",
Tuna: "Tuna",
Trout: "Trout",
}
*/
Intersections are useful for creating "logical AND" types.
const a = z.union([z.number(), z.string()]);
const b = z.union([z.number(), z.boolean()]);
const c = z.intersection(a, b);
type c = z.infer<typeof C>; // => number
const stringAndNumber = z.intersection(z.string(), z.number());
type Never = z.infer<typeof stringAndNumber>; // => never
This is particularly useful for defining "schema mixins" that you can apply to multiple schemas.
const HasId = z.object({
id: z.string(),
});
const BaseTeacher = z.object({
name: z.string(),
});
const Teacher = z.intersection(BaseTeacher, HasId);
type Teacher = z.infer<typeof Teacher>;
// { id:string; name:string };
These differ from arrays in that they have a fixed number of elements, and each element can have a different type.
const athleteSchema = z.tuple([
// takes an array of schemas
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 }]
You can define a recursive schema in Zod, but because of a limitation of TypeScript, their type can't be statically inferred. If you need a recursive Zod schema you'll need to define the type definition manually, and provide it to Zod as a "type hint".
interface Category {
name: string;
subcategories: Category[];
}
const Category: z.ZodType<Category> = z.lazy(() =>
z.object({
name: z.string(),
subcategories: z.array(Category),
}),
);
Category.parse({
name: 'People',
subcategories: [
{
name: 'Politicians',
subcategories: [{ name: 'Presidents', subcategories: [] }],
},
],
}); // passes
Unfortunately this code is a bit duplicative, since you're declaring the types twice: once in the interface and again in the Zod definition. If your schema has lots of primitive fields, there's a way of reducing the amount of duplication:
// define all the non-recursive stuff here
const BaseCategory = z.object({
name: z.string(),
tags: z.array(z.string()),
itemCount: z.number(),
});
// create an interface that extends the base schema
interface Category extends z.infer<typeof BaseCategory> {
subcategories: Category[];
}
// merge the base schema with
// a new Zod schema containing relations
const Category: z.ZodType<Category> = BaseCategory.merge(
z.object({
subcategories: z.lazy(() => z.array(Category)),
}),
);
Validation still works as expected even when there are cycles in the data.
const cyclicalCategory: any = {
name: 'Category A',
};
// creating a cycle
cyclicalCategory.subcategories = [cyclicalCategory];
const parsedCategory = Category.parse(cyclicalCategory); // parses successfully
parsedCategory.subcategories[0].subcategories[0].subcategories[0];
// => parsedCategory: Category;
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) which accepts these arguments.
args: ZodTuple The first argument is a tuple (created with z.tuple([...]) and defines the schema of the arguments to your function. If the function doesn't accept arguments, you can pass an empty tuple (z.tuple([])).returnType: ZodType The second argument is the function's return type. This can be any Zod schema.const args = z.tuple([z.string()]);
const returnType = z.number();
const myFunction = z.function(args, returnType);
type myFunction = z.infer<typeof myFunction>;
// => (arg0: string)=>number
z.function actually returns a higher-order "function factory". Every "factory" has .implement() method which accepts a function as input and returns a new function.
const myValidatedFunction = myFunction(x => {
// TypeScript knows x is a string!
return x.trim().length;
});
myValidatedFunction now automatically validates both its inputs and return value against the schemas provided to z.function. If either is invalid, the function throws.
This way you can confidently write application logic in a "validated function" without worrying about invalid inputs, scattering schema.validate() calls in your endpoint definitions,or writing duplicative types for your functions.
Here's a more complex example showing how to write a typesafe API query endpoint:
const args = z.tuple([
z.object({ nameStartsWith: z.string() }), // filters
z.object({ skip: z.number(), limit: z.number() }), // pagination
]);
const returnType = z.array(
z.object({
id: string(),
name: string(),
}),
);
const FetcherEndpoint = z.function(args, returnType);
const searchUsers = FetcherEndpoint.validate((filters, pagination) => {
// the arguments automatically have the appropriate types
// as defined by the args tuple passed to `z.function()`
// without needing to provide types in the function declaration
filters.nameStartsWith; // autocompletes
filters.ageLessThan; // TypeError
const users = User.findAll({
// ... apply filters here
});
// TypeScript statically verifies that value returned by
// this function is of type { id: string; name: string; }[]
return 'salmon'; // TypeError
});
const users = searchUsers(
{
nameStartsWith: 'John',
},
{
skip: 0,
limit: 20,
},
);
// `typeof users` => { id: string; name: string; }[]
This is particularly useful for defining HTTP or RPC endpoints that accept complex payloads that require validation. Moreover, you can define your endpoints once with Zod and share the code with both your client and server code to achieve end-to-end type safety.
Zod includes a custom Error subclass called ZodError. All validation errors thrown by Zod are instances of ZodError.
A ZodError instance has an errors property of type
// ZodError#errors
{
path: (string | number)[],
message: string
}[]
This array represents all errors Zod encounters when attempting to parse a value.
const person = z.object({
name: {
first: z.string(),
last: z.string(),
},
age: z.number(),
address: z.array(z.string()),
});
try {
person.parse({
name: { first: 'Dave', last: 42 },
age: 'threeve',
address: ['123 Maple Street', {}],
});
} catch (err) {
if (err instanceof ZodError) {
console.log(JSON.stringify(err.errors));
/*
[
{
"path": [ "name", "last" ],
"message": "Non-string type: number"
},
{
"path": [ "age" ],
"message": "Non-number type: string"
},
{
"path": [ "address", 1 ],
"message": "Non-string type: object"
}
]
*/
// err.message returns a formatted error message
console.log(err.message);
/*
`name.last`: Non-string type: number
`age`: Non-number type: string
`address.1`: Non-string type: object
*/
} else {
// should never happen
}
}
There are a handful of other widely-used validation libraries, but all of them have certain design limitations that make for a non-ideal developer experience.
Doesn't support static type inference. š
https://github.com/jquense/yup
Yup is a full-featured library that was implemented first in vanilla JS, with TypeScript typings added later.
Yup supports static type inference, but unfortunately the inferred types aren't actually correct. Currently, the yup package treats all object properties as optional by default:
const schema = yup.object({
asdf: yup.string(),
});
schema.validate({}); // passes
type SchemaType = yup.InferType<typeof schema>;
// returns { asdf: string }
// should be { asdf?: string }
Yup also mis-infers the type of required arrays.
const numList = yup
.array()
.of(yup.string())
.required();
// interpreted as a non-empty list
numList.validateSync([]); // fails
// yet the inferred type doesn't reflect this
type NumList = yup.InferType<typeof numList>;
// returns string[]
// should be [string,...string[]]
These may sound like nitpicks. But it's not acceptable that an object that's assignable to the inferred TypeScript type can fail validation by the validator it was inferred from.
https://github.com/gcanti/io-ts
io-ts is an excellent library by gcanti. The API of io-ts heavily inspired the design of Zod.
In our experience, io-ts prioritizes functional programming purity over developer experience in many cases. This is a valid and admirable design goal, but it makes io-ts particularly hard to integrate into an existing codebase with a more procedural or object-oriented bias.
For instance, consider how to define an object with optional properties in io-ts:
import * as t from 'io-ts';
const A = t.type({
foo: t.string,
});
const B = t.partial({
bar: t.number,
});
const C = t.intersection([A, B]);
type C = t.TypeOf<typeof C>;
// returns { foo: string; bar?: number | undefined }
You must define the required and optional props in separate object validators, pass the optionals through t.partial (which marks all properties as optional), then combine them with t.intersection.
Consider the equivalent in Zod:
const C = z.object({
foo: z.string(),
bar: z.string().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, fp-ts's nomenclature, and the Either monad to do a simple schema validation. It's just not worth it for many people.
https://github.com/pelotom/runtypes
| zod version | release notes |
|---|---|
| zod@1.2.5 | .partial and .deepPartial on object schemas |
| zod@1.2.3 | Date schemas |
| zod@1.2.0 | .pick, .omit, and .augment on object schemas |
| zod@1.1.0 | Records |
| zod@1.0.11 | .nonstrict |
| zod@1.0.10 | Type assertions with .check |
| zod@1.0.4 | Empty tuples |
| zod@1.0.0 | Type assertions, literals, enums, detailed error reporting |
| zod@1.0.0 | Initial release |
FAQs
TypeScript-first schema declaration and validation library with static type inference
We found that zod demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago.Ā It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.