zod

library0.8.0jsnpmunverified

Zod is a TypeScript-first schema declaration and validation library that provides static type inference, ensuring runtime data matches compile-time types. The current stable version is 4.3.6, with frequent patch and minor releases addressing bug fixes, performance improvements, and new features like `z.fromJSONSchema()`.

serialization web-framework database

npm install zod

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · ZOD

zod

serializationjavascriptv0.8.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

✓ import * as z from 'zod'

✗ const z = require('zod')

Zod is primarily designed for use in modern TypeScript and ES module environments.

This example defines a schema for a `User` object, infers its TypeScript type, and demonstrates how to parse valid and invalid data, handling validation errors.

import * as z from "zod"; const UserSchema = z.object({ id: z.string().uuid(), name: z.string().min(1), email: z.string().email(), age: z.number().int().positive().optional(), }); type User = z.infer<typeof UserSchema>; const validUser: User = UserSchema.parse({ id: "a1b2c3d4-e5f6-7890-1234-567890abcdef", name: "Alice", email: "alice@example.com", }); console.log("Parsed user:", validUser); // Expected output: Parsed user: { id: '...', name: 'Alice', email: 'alice@example.com' } try { UserSchema.parse({ id: "invalid-uuid", name: "", email: "not-an-email", }); } catch (error) { console.error("Validation error:\n", error); // Expected output (abbreviated): Validation error: ZodError: [ { code: 'invalid_string', validation: 'uuid', ... }, { code: 'too_small', minimum: 1, ... }, { code: 'invalid_string', validation: 'email', ... } ] }

Debug

Known issues

deprecatedThe `message` property directly on individual Zod schema validators (e.g., `z.string().min(1, { message: '...' })`) has been deprecated.

fix

For custom messages, use `.refine(val => condition, { message: 'Your custom message' })` or define a global custom error map with `z.setErrorMap()`.

affects: >=4.3.5

gotcha`z.date()` expects a `Date` object, not a date string. Passing a string will typically result in an 'Invalid date' error unless it can be reliably converted by JavaScript's `Date` constructor.

fix

Use `z.coerce.date()` to automatically convert date strings to `Date` objects, or explicitly convert the string to a `Date` object before parsing.

affects: >=4.0.0

gotchaBy default, `z.object()` schemas are 'strict', meaning they will strip or error on unknown keys in the input object. This can lead to unexpected data loss or validation failures.

fix

Use `z.object(...).passthrough()` to allow unknown keys, or `z.object(...).strip()` to remove them without erroring.

affects: >=3.0.0

gotcha`z.refine()` is always synchronous. For asynchronous validations (e.g., checking uniqueness against a database), it will not correctly await Promises.

fix

For asynchronous validation, use `z.superRefine(async (value, ctx) => { /* ... */ })` and ensure you await any async operations within it.

affects: >=3.0.0

Errors

Common errors & fixes

ZodError: [ { "code": "invalid_type", "expected": "date", "received": "string", "path": [ "myDate" ], "message": "Expected date, received string" } ]

Attempting to parse a date string directly with `z.date()` instead of a `Date` object.

fix

Change the schema to `z.coerce.date()` to enable automatic string-to-Date conversion upon parsing.

ZodError: [ { "code": "unrecognized_keys", "keys": [ "extraField" ] } ]

Input object contains keys not defined in a `z.object()` schema that is in default 'strict' mode.

fix

If extra keys should be allowed, modify your schema to `z.object({ /* ... */ }).passthrough()`. If they should be ignored, use `z.object({ /* ... */ }).strip()`.

TypeError: Cannot read properties of undefined (reading 'parse')

The Zod schema variable is `undefined` at the point of calling `.parse()` or `.safeParse()`, typically due to an incorrect import or variable scope issue.

fix

Verify that `import * as z from 'zod';` is correctly placed and that your schema variable is defined and accessible where `.parse()` is called.

Type 'string' is not assignable to type 'ZodObject<...>' (TypeScript error)

Attempting to use a Zod schema directly where its inferred type is expected, or passing data to a function that expects a schema instance without calling a parsing method.

fix

Always call `.parse(data)` or `.safeParse(data)` on your schema instance to validate and extract the typed value.

Upgrade

Version history

0.8.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

55 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/colinhacks/zod ↗

packagehttps://www.npmjs.com/package/zod ↗

homepagehttps://zod.dev ↗