Boundary validation
Validate request bodies, form submissions, or other untrusted values while keeping control flow explicit.
Zod · Function
safeParse
safeParse validates data without throwing on validation failure. It returns either parsed data on success or a ZodError on failure, distinguished by the result's success field.
How it works
Call safeParse on a Zod schema with unknown input. It returns a discriminated result: a successful branch containing parsed data or a failure branch containing a ZodError, so callers can branch on success instead of wrapping parse in try/catch.
Syntax
schema.safeParse(data: unknown): { success: true; data: T } | { success: false; error: ZodError }Parameters
| Name | Type | Description |
|---|---|---|
data | unknown | The value to validate and parse; it is accepted as unknown input. |
Returns
A discriminated union: { success: true; data: T } on success, or { success: false; error: ZodError } on failure.
Key points
- Use safeParse when validation failure should be represented as data instead of handled through a try/catch block.
- The success field discriminates the result union, enabling type-safe handling of valid and invalid outcomes.
- The failure branch exposes error as a ZodError instance for inspecting validation problems.
- The success branch exposes data containing the schema-validated and parsed value.
- Schemas with asynchronous refinements or transforms require the asynchronous safeParse variant.
Common mistakes
- Use safeParseAsync when the schema contains asynchronous refinements or transforms; safeParse is for synchronous parsing.
Example: Validate without exceptions
import { z } from "zod";
const Player = z.object({
username: z.string(),
xp: z.number(),
});
const result = Player.safeParse({ username: 42, xp: "100" });
if (!result.success) {
console.error(result.error);
} else {
console.log(result.data);
}Checks the input without throwing, then uses the discriminant to access either the validation error or parsed data.
When to use it
Result-based APIs
Return validation outcomes from a function without requiring callers to catch exceptions.
Error reporting
Inspect structured validation details and present useful feedback to users.
Interview questions
QHow does safeParse differ from parse?
safeParse validates and returns a plain result object rather than throwing when validation fails. The result is a discriminated union with either success and data or failure and error.
Follow-up: What should you use for asynchronous refinements? Use safeParseAsync, because the synchronous method does not handle those asynchronous schema APIs.
QHow should callers consume the returned value?
Check result.success before reading result.data or result.error. A successful result contains the parsed value, while an unsuccessful result contains a ZodError with validation details.
Follow-up: Why is checking success useful in TypeScript? It narrows the discriminated union so each branch exposes only its valid property.
QWhat are the input and output shapes?
The input parameter is typed as unknown, so safeParse can accept untrusted data. The returned data is the schema's parsed type, while failures expose a ZodError.
Follow-up: How can asynchronous validation avoid exceptions? Await schema.safeParseAsync(input) and branch on its success field.
Related
parsesafeParseAsyncZodError