Zod is a TypeScript-first schema declaration and validation library designed to ensure both compile-time type safety and runtime data validation.

If you’re working with modern JavaScript or TypeScript applications, Zod helps you validate inputs, API responses, and complex data structures with ease — all while keeping your codebase clean, type-safe, and developer-friendly.

Zod is available on npm and maintained actively on GitHub. It’s a lightweight and powerful alternative to larger libraries like Joi or Yup — offering a much tighter integration with the TypeScript type system.

So, what problem does Zod solve? It eliminates the disconnect between your TypeScript types and actual runtime validation. With Zod, you write your validation logic once, and TypeScript automatically infers the types — no duplication required.

Whether you’re validating forms, parsing JSON, or building APIs, Zod makes it effortless. Curious how it works? Here’s a quick Zod example:

import { z } from 'zod';

const userSchema = z.object({
  name: z.string(),
  email: z.string().email(),
  age: z.number().int().positive(),
});

userSchema.parse({
  name: "Sharukhan Patan",
  email: "sharukhanpatan@example.com",
  age: 25,
});

Want to learn more? Explore the official Zod documentation or dive into practical use cases in our full guide.

Primitives & Basic Types in Zod

Zod supports all major JavaScript primitives:

• Primitives: z.string(), z.number(), z.boolean(), z.bigint(), z.date()
• Booleans: Use z.boolean() for strict boolean validation.
• Numbers & Integers: Validate numbers with z.number() and ensure integers using .int().
• BigInts: For large numbers exceeding 64-bit precision.
• Dates: Use z.date() for Date object validation.

Strings & Formats in Zod

Enhances string validation with format checks:

• Strings: z.string() with methods like .min(), .max(), .regex()
• String Formats:
  • z.string().email() – Emails
  • z.string().uuid() – UUIDs
  • z.string().url() – URLs
  • z.string().ip() – IP addresses
  • z.string().datetime() – ISO datetime
  • z.string().date() – ISO date
  • z.string().time() – ISO time
  • z.string().includes(), startsWith(), endsWith() – string operations
• Stringbools: Convert "true" or "false" to actual booleans using coercion

Literals & Enums in Zod

Validate fixed values using literals or sets:

• Literals: z.literal('active'), z.literal(1), etc.
• Literal Unions: Combine multiple values via z.union([z.literal('a'), z.literal('b')])
• Enums:
  • z.enum(['admin', 'user']) for string enums
  • .enum – keyword alias for defining enum types
  • .exclude(), .extract() – filter enum variants
  • Compare: zod enum vs literal

Objects & Object Utilities in Zod

Zod offers powerful utilities for defining and extending objects:

• Basic Object: z.object({ name: z.string() })
• Strict vs Loose:
  • z.strictObject() – disallow unknown keys
  • z.looseObject() – allow unknown keys
• Utilities:
  • .shape(), .keyof(), .extend(), .pick(), .omit(), .partial(), .required()
  • .catchall() – allow extra properties
• Recursive objects: Create nested schemas using z.lazy()
• Circularity errors: Solve by wrapping references with z.lazy()

Arrays, Tuples & Unions in Zod

Working with collections and multiple type options:

• Arrays: z.array(z.string())
• Tuples: Fixed-length, typed arrays
• Unions: z.union([z.string(), z.number()])
• Discriminated Unions: For object shapes with a shared tag/key
• Intersections: Combine multiple schemas: z.intersection(A, B)

For a focused guide on string arrays, see Zod Array of Strings.

To handle numeric arrays with validations like range or positivity, check out Zod Array of Numbers.

Advanced Structures in Zod

Zod supports several advanced data structures beyond standard objects and arrays. Use z.record() to validate object maps with consistent key-value types — perfect for dictionaries or dynamic objects.

Zod also offers native support for Map and Set via z.map() and z.set(), ensuring proper shape and content validation. For file uploads or browser blobs, z.instanceof(Blob) can validate file-like objects.

You can also validate class instances using z.instanceof(Class). Note that z.promise() is deprecated in Zod 4, as schema-based promise validation has been removed in favor of cleaner async validation patterns.

• Records: Object maps with uniform key-value types
• Maps & Sets: Validate native Map and Set using z.map() and z.set()
• Files: Validate file-like objects (e.g., Blob)
• Promises: Schema for promise results using z.promise() [deprecated in zod 4]
• Instanceof: Use z.instanceof(Class) for class validations

Refinements & Custom Validations in Zod

Zod offers refinement methods to add custom validation logic beyond built-in rules. Use .refine() for simple post-validation checks, like confirming passwords match or a number is even.

The .check() method, introduced in Zod 4, allows you to return multiple validation issues at once for better error reporting. While .superRefine() previously provided contextual access for complex logic, it’s now deprecated in favor of .check().

These refinements make Zod highly extensible and ideal for enforcing business rules in TypeScript-based schema validation.

• .refine() – for simple post-validation logic
• .superRefine() – granular access to the validation context [deprecated in zod 4]
• .check() – create multiple issues in a single refinement

Custom Error Messages: Supply second argument to .refine()

Transforms & Preprocessing in Zod

Zod supports powerful data transformation features to reshape input and output during validation. Use .transform() to modify the result after successful parsing, and .preprocess() to sanitize or convert raw input before validation runs.

For more complex workflows, .pipe() lets you chain schemas with transformations, refinements, or validations in a clear, composable way. These tools are ideal for normalizing form data, formatting API responses, or handling custom logic during schema validation.

• .transform() – modify the output of a schema
• .preprocess() – sanitize or convert raw input before validation
• Pipes: Chain transforms and refinements with .pipe()

Defaults, Optionals & Nullables in Zod

to allow undefined, .nullable() to allow null, and nullish logic to accept both. The .default() method assigns default values when a field is missing, while prefaults combine .optional().default() for more control.

Explore more use cases in our complete guide to using .default() in Zod schemas

Need defaults by type? See our guide on how to use .default() with each Zod type →

For practical strategies on handling complex defaults efficiently, explore this guide to advanced default handling in Zod.

With .catch(), you can recover from validation errors and provide fallback values at runtime. These features make it easy to manage optional, nullable, and defaultable fields in both TypeScript and JavaScript applications.

• Optionals: z.string().optional()
• Nullables: z.string().nullable()
• Nullish: Accepts both null and undefined
• Defaults: z.string().default('tecktol')
• Prefaults: Use .optional().default() combo
• Catch: .catch() to handle fallback value on failure

Special Types & Helpers in Zod

Zod offers several advanced schema types for specialized use cases. z.unknown() accepts any value, making it useful for deferring validation. z.never() matches no values and is ideal for enforcing exhaustive type checks.

Zod also supports readonly schemas to prevent object mutation, branded types using .brand() for creating nominal typing, and simulates template literal types using refinements for pattern-based string validation.

These tools help developers handle edge cases while maintaining strong type safety and runtime guarantees.

• Unknown: z.unknown() accepts any value
• Never: z.never() matches nothing (useful for exhaustive checks)
• Readonly: Prevent modifications
• Branded types: Use .brand() for type-safe tagging
• Template literals: (not native, but simulated via refinements)

Function Schemas & JSON in Zod

Zod allows you to validate function types using z.function(), where you can strictly define the parameter types with .args() and the return type with .returns(). This ensures your functions conform to expected signatures at runtime.

For working with structured data, Zod supports recursive shapes to define valid JSON schemas — allowing you to handle deeply nested objects and arrays using z.lazy() and unions. These features are essential when validating user-defined callbacks or parsing complex JSON data in TypeScript applications.

• Functions: Validate function types using z.function()
• JSON: Define valid JSON schemas using recursive shapes

Conclusion

Zod offers a vast set of features that cater to both beginner and advanced developers. From primitives to recursive objects and transformations, it helps keep your data validations tight and your TypeScript code clean.