zod

<p align="center"> <img src="logo.svg" width="200px" align="center" alt="Zod logo" /> <h1 align="center">Zod</h1> <p align="center"> ✨ <a href="https://zod.dev">https://zod.dev</a> ✨ <br/> TypeScript-first schema validation with static type inference </p> </p> <br/> <p align="center"> <a href="https://github.com/colinhacks/zod/actions?query=branch%3Amain"><img src="https://github.com/colinhacks/zod/actions/workflows/test.yml/badge.svg?event=push&branch=main" alt="Zod CI status" /></a> <a href="https://twitter.com/colinhacks" rel="nofollow"><img src="https://img.shields.io/badge/created%20by-@colinhacks-4BBAAB.svg" alt="Created by Colin McDonnell"></a> <a href="https://opensource.org/licenses/MIT" rel="nofollow"><img src="https://img.shields.io/github/license/colinhacks/zod" alt="License"></a> <a href="https://www.npmjs.com/package/zod" rel="nofollow"><img src="https://img.shields.io/npm/dw/zod.svg" alt="npm"></a> <a href="https://www.npmjs.com/package/zod" rel="nofollow"><img src="https://img.shields.io/github/stars/colinhacks/zod" alt="stars"></a> </p> <div align="center"> <a href="https://zod.dev">Documentation</a> <span>&nbsp;&nbsp;•&nbsp;&nbsp;</span> <a href="https://discord.gg/RcG33DQJdf">Discord</a> <span>&nbsp;&nbsp;•&nbsp;&nbsp;</span> <a href="https://www.npmjs.com/package/zod">npm</a> <span>&nbsp;&nbsp;•&nbsp;&nbsp;</span> <a href="https://deno.land/x/zod">deno</a> <span>&nbsp;&nbsp;•&nbsp;&nbsp;</span> <a href="https://github.com/colinhacks/zod/issues/new">Issues</a> <span>&nbsp;&nbsp;•&nbsp;&nbsp;</span> <a href="https://twitter.com/colinhacks">@colinhacks</a> <span>&nbsp;&nbsp;•&nbsp;&nbsp;</span> <a href="https://trpc.io">tRPC</a> <br /> </div> <br/> <br/> <!-- <p><strong>Announcement ✨</strong> Zod has recieved the <a href="https://go.clerk.com/zod-clerk">Clerk</a> OSS Fellowship!<br/>Read the announcement post 👉 <a href="https://go.clerk.com/zod-clerk">clerk.com/blog/zod-fellowship</a></p> -->

<br/>

Table of contents

These docs have been translated into Chinese.

• Table of contents
• Introduction
  • Sponsors
    • Platinum
    • Gold
    • Silver
    • Bronze
    • Copper
  • Ecosystem
    • Resources
    • API libraries
    • Form integrations
    • Zod to X
    • X to Zod
    • Mocking
    • Powered by Zod
    • Utilities for Zod
• Installation
  • Requirements
  • From npm (Node/Bun)
  • From deno.land/x (Deno)
• Basic usage
• Primitives
• Coercion for primitives
• Literals
• Strings
  • Datetimes
  • Dates
  • Times
  • IP addresses
• Numbers
• BigInts
• NaNs
• Booleans
• Dates
• Zod enums
• Native enums
• Optionals
• Nullables
• Objects
  • .shape
  • .keyof
  • .extend
  • .merge
  • .pick/.omit
  • .partial
  • .deepPartial
  • .required
  • .passthrough
  • .strict
  • .strip
  • .catchall
• Arrays
  • .element
  • .nonempty
  • .min/.max/.length
• Tuples
• Unions
• Discriminated unions
• Records
  • Record key type
• Maps
• Sets
• Intersections
• Recursive types
  • ZodType with ZodEffects
  • JSON type
  • Cyclical objects
• Promises
• Instanceof
• Functions
• Preprocess
• Custom schemas
• Schema methods
  • .parse
  • .parseAsync
  • .safeParse
  • .safeParseAsync
  • .refine
    • Arguments
    • Customize error path
    • Asynchronous refinements
    • Relationship to transforms
  • .superRefine
    • Abort early
    • Type refinements
  • .transform
    • Chaining order
    • Validating during transform
    • Relationship to refinements
    • Async transforms
  • .default
  • .describe
  • .catch
  • .optional
  • .nullable
  • .nullish
  • .array
  • .promise
  • .or
  • .and
  • .brand
  • .readonly
  • .pipe
    • You can use .pipe() to fix common issues with z.coerce.
• Guides and concepts
  • Type inference
  • Writing generic functions
    • Constraining allowable inputs
  • Error handling
  • Error formatting
• Comparison
  • Joi
  • Yup
  • io-ts
  • Runtypes
  • Ow
• 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
• Works with plain JavaScript too! You don't need to use TypeScript.

Sponsors

Sponsorship at any level is appreciated and encouraged. If you built a paid product using Zod, consider one of the corporate tiers.

<br/> <h3 align="center">Diamond</h3> <br/> <div align="center"> <a href="https://go.clerk.com/PKHrcwh"> <picture width="100%"> <source media="(prefers-color-scheme: dark)" srcset="https://github.com/colinhacks/zod/assets/3084745/15c8c8be-189d-44ed-b3db-59bf2a21cbe3"> <img alt="clerk logo" src="https://github.com/colinhacks/zod/assets/3084745/15c8c8be-189d-44ed-b3db-59bf2a21cbe3"> </picture> </a> <br/> <br/> <p> The most comprehensive User Management Platform <br/> <a style="text-decoration:none;" href="https://go.clerk.com/PKHrcwh" target="_blank">clerk.com</a> </p> </div> <br/> <br/> <h3 align="center">Platinum</h3> <table align="center" style="justify-content: center;align-items: center;display: flex;"> <tr> <td align="center"> <p></p> <p> <a href="https://neon.tech"> <picture height="68px"> <source media="(prefers-color-scheme: dark)" srcset="https://github.com/user-attachments/assets/83b4b1b1-a9ab-4ae5-a632-56d282f0c444"> <img alt="stainless" height="68px" src="https://github.com/user-attachments/assets/83b4b1b1-a9ab-4ae5-a632-56d282f0c444"> </picture> </a> <br /> Serverless Postgres — Ship faster <br/> <a href="https://neon.tech" style="text-decoration:none;">neon.tech</a> </p> <p></p> </td> </tr> <tr> <td align="center"> <p></p> <p> <a href="https://retool.com/?utm_source=github&utm_medium=referral&utm_campaign=zod"> <picture height="45px"> <source media="(prefers-color-scheme: dark)" srcset="https://github.com/colinhacks/zod/assets/3084745/ac65013f-aeb4-48dd-a2ee-41040b69cbe6"> <img alt="stainless" height="45px" src="https://github.com/colinhacks/zod/assets/3084745/5ef4c11b-efeb-4495-90a8-41b83f798600"> </picture> </a> <br /> Build AI apps and workflows with <a href="https://retool.com/products/ai?utm_source=github&utm_medium=referral&utm_campaign=zod">Retool AI</a> <br/> <a href="https://retool.com/?utm_source=github&utm_medium=referral&utm_campaign=zod" style="text-decoration:none;">retool.com</a> </p> <p></p> </td> </tr> <tr> <td align="center"> <p></p> <p> <a href="https://stainlessapi.com"> <picture height="45px"> <source media="(prefers-color-scheme: dark)" srcset="https://github.com/colinhacks/zod/assets/3084745/f20759c1-3e51-49d0-a31e-bbc43abec665"> <img alt="stainless" height="45px" src="https://github.com/colinhacks/zod/assets/3084745/e9444e44-d991-4bba-a697-dbcfad608e47"> </picture> </a> <br /> Generate best-in-class SDKs <br/> <a href="https://stainlessapi.com" style="text-decoration:none;">stainlessapi.com</a> </p> <p></p> </td> </tr> <tr> <td align="center"> <p></p> <p> <a href="https://speakeasy.com/?utm_source=zod+docs"> <picture height="40px"> <source media="(prefers-color-scheme: dark)" srcset="https://github.com/colinhacks/zod/assets/3084745/b1d86601-c7fb-483c-9927-5dc24ce8b737"> <img alt="speakeasy" height="40px" src="https://github.com/colinhacks/zod/assets/3084745/647524a4-22bb-4199-be70-404207a5a2b5"> </picture> </a> <br /> SDKs & Terraform providers for your API <br/> <a href="https://speakeasy.com/?utm_source=zod+docs" style="text-decoration:none;">speakeasy.com</a> </p> <p></p> </td> </tr> </table> <br/> <h3 align="center">Gold</h3> <table align="center" style="justify-content: center;align-items: center;display: flex;"> <tr> <td align="center"> <img src="https://avatars.githubusercontent.com/u/89474619?s=200&v=4" height="50px;" alt="PropelAuth" /> <br /> <a style="text-decoration:none;" href="https://www.propelauth.com/" target="_blank">PropelAuth</a> </td> <td align="center"> <img src="https://avatars.githubusercontent.com/u/80861386?s=200&v=4" height="50px;" alt="Cerbos" /> <br /> <a style="text-decoration:none;" href="https://cerbos.dev/" target="_blank">Cerbos</a> </td> <td align="center"> <img src="https://avatars.githubusercontent.com/u/301879?s=200&v=4" height="50px;" alt="Scalar.com logo" /> <br /> <a style="text-decoration:none;" href="https://scalar.com/" target="_blank">Scalar</a> </td> <td align="center"> <img src="https://avatars.githubusercontent.com/u/95297378?s=200&v=4" height="50px;" alt="Trigger.dev logo" /> <br /> <a style="text-decoration:none;" href="https://trigger.dev" target="_blank">Trigger.dev</a> </td> </tr><tr> <td align="center"> <img src="https://avatars.githubusercontent.com/u/125754?s=200&v=4" height="50px;" alt="Transloadit logo" /> <br /> <a style="text-decoration:none;" href="https://transloadit.com/?utm_source=zod&utm_medium=refe rral&utm_campaign=sponsorship&utm_content=github" target="_blank">Transloadit</a> </td> <td align="center"> <img src="https://avatars.githubusercontent.com/u/107880645?s=200&v=4" height="50px;" alt="Infisical logo" /> <br /> <a style="text-decoration:none;" href="https://infisical.com" target="_blank">Infisical</a> </td>