Zod

TypeScript-first schema validation with static type inference
by @colinhacks

Featured sponsor: Jazz

Read the docs →

What is Zod?

Zod is a TypeScript-first validation library. Define a schema and parse some data with it. You'll get back a strongly typed, validated result.

1import * as z from "zod";
2
3const User = z.object({
4  name: z.string(),
5});
6
7// some untrusted data...
8const input = {
9  /* stuff */
10};
11
12// the parsed result is validated and type safe!
13const data = User.parse(input);
14
15// so you can use it with confidence :)
16console.log(data.name);

Features

• Zero external dependencies
• Works in Node.js and all modern browsers
• Tiny: 2kb core bundle (gzipped)
• Immutable API: methods return a new instance
• Concise interface
• Works with TypeScript and plain JS
• Built-in JSON Schema conversion
• Extensive ecosystem

Installation

1npm install zod

Basic usage

Before you can do anything else, you need to define a schema. For the purposes of this guide, we'll use a simple object schema.

1import * as z from "zod";
2
3const Player = z.object({
4  username: z.string(),
5  xp: z.number(),
6});

Parsing data

Given any Zod schema, use .parse to validate an input. If it's valid, Zod returns a strongly-typed deep clone of the input.

1Player.parse({ username: "billie", xp: 100 });
2// => returns { username: "billie", xp: 100 }

Note — If your schema uses certain asynchronous APIs like async refinements or transforms, you'll need to use the .parseAsync() method instead.

1const schema = z.string().refine(async (val) => val.length <= 8);
2
3await schema.parseAsync("hello");
4// => "hello"

Handling errors

When validation fails, the .parse() method will throw a ZodError instance with granular information about the validation issues.

1try {
2  Player.parse({ username: 42, xp: "100" });
3} catch (err) {
4  if (err instanceof z.ZodError) {
5    err.issues;
6    /* [
7      {
8        expected: 'string',
9        code: 'invalid_type',
10        path: [ 'username' ],
11        message: 'Invalid input: expected string'
12      },
13      {
14        expected: 'number',
15        code: 'invalid_type',
16        path: [ 'xp' ],
17        message: 'Invalid input: expected number'
18      }
19    ] */
20  }
21}

To avoid a try/catch block, you can use the .safeParse() method to get back a plain result object containing either the successfully parsed data or a ZodError. The result type is a discriminated union, so you can handle both cases conveniently.

1const result = Player.safeParse({ username: 42, xp: "100" });
2if (!result.success) {
3  result.error; // ZodError instance
4} else {
5  result.data; // { username: string; xp: number }
6}

Note — If your schema uses certain asynchronous APIs like async refinements or transforms, you'll need to use the .safeParseAsync() method instead.

1const schema = z.string().refine(async (val) => val.length <= 8);
2
3await schema.safeParseAsync("hello");
4// => { success: true; data: "hello" }

Inferring types

Zod infers a static type from your schema definitions. You can extract this type with the z.infer<> utility and use it however you like.

1const Player = z.object({
2  username: z.string(),
3  xp: z.number(),
4});
5
6// extract the inferred type
7type Player = z.infer<typeof Player>;
8
9// use it in your code
10const player: Player = { username: "billie", xp: 100 };

In some cases, the input & output types of a schema can diverge. For instance, the .transform() API can convert the input from one type to another. In these cases, you can extract the input and output types independently:

1const mySchema = z.string().transform((val) => val.length);
2
3type MySchemaIn = z.input<typeof mySchema>;
4// => string
5
6type MySchemaOut = z.output<typeof mySchema>; // equivalent to z.infer<typeof mySchema>
7// number