Zod is a powerful TypeScript-first schema validation library that makes it easy to define, validate, and transform data. Whether you're working on a small project or a large-scale application, Zod's schema methods provide the flexibility and robustness you need to ensure your data is valid and type-safe.
In this article, we'll explore the most commonly used Zod schema methods, complete with examples and practical use cases. By the end, you'll have a solid understanding of how to use Zod effectively in your projects.
What Are Zod Schema Methods?
Zod schema methods are functions that allow you to define, refine, and manipulate schemas. These methods enable you to:
Validate data: Ensure that your data matches the expected structure and type.
Transform data: Modify data after validation.
Handle edge cases: Provide fallback values, handle optional fields, and more.
Create complex schemas: Combine multiple schemas to validate nested or complex data structures.
Let’s dive into the most important Zod schema methods and how to use them.
1. Core Validation Methods
.parse()
The .parse() method validates and parses the input data. If the data doesn't match the schema, it throws a ZodError.
import { z } from 'zod';
const schema = z.string();
const result = schema.parse("hello"); // Returns "hello"
schema.parse(42); // Throws ZodError
Use Case: Use .parse() when you want to enforce strict validation and handle errors explicitly.
.safeParse()
The .safeParse() method validates the input data without throwing an error. Instead, it returns a result object that indicates whether the validation succeeded or failed.
const schema = z.string();
const result = schema.safeParse("hello");
if (result.success) {
console.log(result.data); // "hello"
} else {
console.log(result.error); // ZodError
}
Use Case: Use .safeParse() when you want to handle validation errors gracefully without crashing your application.
.parseAsync() and .safeParseAsync()
These methods are the asynchronous versions of .parse() and .safeParse(). They return promises and are useful for validating asynchronous data (e.g., API responses).
const schema = z.string();
schema.parseAsync("hello").then(console.log); // Returns "hello"
schema.safeParseAsync(42).then((result) => {
if (result.success) {
console.log(result.data);
} else {
console.log(result.error);
}
});
Use Case: Use .parseAsync() and .safeParseAsync() when working with asynchronous data sources.
2. Custom Validation Methods
.refine()
The .refine() method allows you to add custom validation logic to your schema.
const schema = z.string().refine((val) => val.length > 5, {
message: "String must be longer than 5 characters",
});
schema.parse("hello world"); // Valid
schema.parse("hi"); // Throws ZodError
Use Case: Use .refine() to enforce custom validation rules that aren't covered by Zod's built-in methods.
.superRefine()
The .superRefine() method is a more advanced version of .refine(). It allows you to accumulate multiple validation errors.
const schema = z.string().superRefine((val, ctx) => {
if (val.length < 5) {
ctx.addIssue({
code: z.ZodIssueCode.too_small,
minimum: 5,
type: "string",
inclusive: true,
message: "String must be at least 5 characters",
});
}
if (!val.includes(" ")) {
ctx.addIssue({
code: z.ZodIssueCode.custom,
message: "String must contain a space",
});
}
});
schema.parse("hello world"); // Valid
schema.parse("hi"); // Throws ZodError with multiple issues
Use Case: Use .superRefine() when you need to validate multiple conditions and report all errors at once.
3. Data Transformation Methods
.transform()
The .transform() method allows you to modify the data after validation.
const schema = z.string().transform((val) => val.toUpperCase());
const result = schema.parse("hello"); // Returns "HELLO"
Use Case: Use .transform() to clean or normalize data after validation.
.pipe()
The .pipe() method allows you to chain multiple schemas together. The output of one schema is passed as input to the next.
const schema = z.string().pipe(z.number().transform((val) => val * 2));
const result = schema.parse("42"); // Returns 84
Use Case: Use .pipe() to create complex validation and transformation pipelines.
4. Handling Optional and Nullable Fields
.optional()
The .optional() method makes a field optional.
const schema = z.object({
name: z.string(),
age: z.number().optional(),
});
schema.parse({ name: "John" }); // Valid
Use Case: Use .optional() when a field is not required.
.nullable()
The .nullable() method makes a field nullable.
const schema = z.object({
name: z.string(),
age: z.number().nullable(),
});
schema.parse({ name: "John", age: null }); // Valid
Use Case: Use .nullable() when a field can explicitly be null.
.nullish()
The .nullish() method makes a field both optional and nullable.
const schema = z.object({
name: z.string(),
age: z.number().nullish(),
});
schema.parse({ name: "John" }); // Valid
schema.parse({ name: "John", age: null }); // Valid
Use Case: Use .nullish() when a field can be undefined or null.
5. Fallback and Default Values
.default()
The .default() method provides a default value if the input is undefined.
const schema = z.string().default("hello");
const result = schema.parse(undefined); // Returns "hello"
Use Case: Use .default() to ensure a field always has a value, even if it's missing from the input.
.catch()
The .catch() method provides a fallback value if validation fails.
const schema = z.number().catch(42);
const result = schema.parse("invalid"); // Returns 42
Use Case: Use .catch() to handle invalid data gracefully.
6. Advanced Schema Methods
.array()
The .array() method defines an array schema.
const schema = z.array(z.string());
schema.parse(["hello", "world"]); // Valid
schema.parse([1, 2]); // Throws ZodError
Use Case: Use .array() to validate arrays of a specific type.
.brand()
The .brand() method adds a "brand" to the schema, which is useful for nominal typing.
const schema = z.string().brand<"Email">();
type Email = z.infer<typeof schema>; // string & { __brand: "Email" }
Use Case: Use .brand() to create distinct types for values that share the same underlying type.
.readonly()
The .readonly() method makes the schema read-only.
const schema = z.object({ name: z.string() }).readonly();
const result = schema.parse({ name: "John" });
result.name = "Jane"; // TypeScript error (read-only)
Use Case: Use .readonly() to enforce immutability.
Conclusion
Zod's schema methods provide a powerful and flexible way to define, validate, and transform data. Whether you're working with simple or complex data structures, Zod has the tools you need to ensure your data is valid and type-safe.
By mastering these methods, you can build robust applications with confidence. For more advanced use cases, check out the official Zod documentation.
Happy coding! 🚀