{"id":10435,"library":"zod","title":"Zod","description":"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()`.","status":"active","version":"4.3.6","language":"javascript","source_language":"en","source_url":"https://github.com/colinhacks/zod","tags":["javascript","typescript","schema","validation","type","inference"],"install":[{"cmd":"npm install zod","lang":"bash","label":"npm"},{"cmd":"yarn add zod","lang":"bash","label":"yarn"},{"cmd":"pnpm add zod","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Zod is primarily designed for use in modern TypeScript and ES module environments.","wrong":"const z = require('zod')","symbol":"z","correct":"import * as z from 'zod'"}],"quickstart":{"code":"import * as z from \"zod\";\n\nconst UserSchema = z.object({\n  id: z.string().uuid(),\n  name: z.string().min(1),\n  email: z.string().email(),\n  age: z.number().int().positive().optional(),\n});\n\ntype User = z.infer<typeof UserSchema>;\n\nconst validUser: User = UserSchema.parse({\n  id: \"a1b2c3d4-e5f6-7890-1234-567890abcdef\",\n  name: \"Alice\",\n  email: \"alice@example.com\",\n});\n\nconsole.log(\"Parsed user:\", validUser);\n// Expected output: Parsed user: { id: '...', name: 'Alice', email: 'alice@example.com' }\n\ntry {\n  UserSchema.parse({\n    id: \"invalid-uuid\",\n    name: \"\",\n    email: \"not-an-email\",\n  });\n} catch (error) {\n  console.error(\"Validation error:\\n\", error);\n  // Expected output (abbreviated): Validation error:\nZodError: [\n  { code: 'invalid_string', validation: 'uuid', ... },\n  { code: 'too_small', minimum: 1, ... },\n  { code: 'invalid_string', validation: 'email', ... }\n]\n}\n","lang":"typescript","description":"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."},"warnings":[{"fix":"For custom messages, use `.refine(val => condition, { message: 'Your custom message' })` or define a global custom error map with `z.setErrorMap()`.","message":"The `message` property directly on individual Zod schema validators (e.g., `z.string().min(1, { message: '...' })`) has been deprecated.","severity":"deprecated","affected_versions":">=4.3.5"},{"fix":"Use `z.coerce.date()` to automatically convert date strings to `Date` objects, or explicitly convert the string to a `Date` object before parsing.","message":"`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.","severity":"gotcha","affected_versions":">=4.0.0"},{"fix":"Use `z.object(...).passthrough()` to allow unknown keys, or `z.object(...).strip()` to remove them without erroring.","message":"By 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.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"For asynchronous validation, use `z.superRefine(async (value, ctx) => { /* ... */ })` and ensure you await any async operations within it.","message":"`z.refine()` is always synchronous. For asynchronous validations (e.g., checking uniqueness against a database), it will not correctly await Promises.","severity":"gotcha","affected_versions":">=3.0.0"}],"env_vars":null,"last_verified":"2026-04-18T00:00:00.000Z","next_check":"2026-07-17T00:00:00.000Z","problems":[{"fix":"Change the schema to `z.coerce.date()` to enable automatic string-to-Date conversion upon parsing.","cause":"Attempting to parse a date string directly with `z.date()` instead of a `Date` object.","error":"ZodError: [ { \"code\": \"invalid_type\", \"expected\": \"date\", \"received\": \"string\", \"path\": [ \"myDate\" ], \"message\": \"Expected date, received string\" } ]"},{"fix":"If extra keys should be allowed, modify your schema to `z.object({ /* ... */ }).passthrough()`. If they should be ignored, use `z.object({ /* ... */ }).strip()`.","cause":"Input object contains keys not defined in a `z.object()` schema that is in default 'strict' mode.","error":"ZodError: [ { \"code\": \"unrecognized_keys\", \"keys\": [ \"extraField\" ] } ]"},{"fix":"Verify that `import * as z from 'zod';` is correctly placed and that your schema variable is defined and accessible where `.parse()` is called.","cause":"The Zod schema variable is `undefined` at the point of calling `.parse()` or `.safeParse()`, typically due to an incorrect import or variable scope issue.","error":"TypeError: Cannot read properties of undefined (reading 'parse')"},{"fix":"Always call `.parse(data)` or `.safeParse(data)` on your schema instance to validate and extract the typed value.","cause":"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.","error":"Type 'string' is not assignable to type 'ZodObject<...>' (TypeScript error)"}],"ecosystem":"npm"}