Boundary validation
Validate request bodies, configuration, or other external data before application logic consumes it.
Zod · Function
parse
Validates unknown input against a Zod schema. It returns a strongly typed deep clone on success and throws a ZodError on failure.
How it works
Call parse on a Zod schema with unknown input. When validation succeeds, it returns a strongly typed deep clone; when validation fails, it throws a ZodError, so use try/catch when handling expected invalid input.
Syntax
schema.parse(data: unknown): TParameters
| Name | Type | Description |
|---|---|---|
data | unknown | The value to validate against the schema; its compile-time type is unknown. |
Returns
T on success; throws ZodError when validation fails.
Key points
- Invoke parse as a method on an existing Zod schema to validate an input value.
- Successful parsing produces a strongly typed deep clone rather than the original reference.
- Failures throw ZodError, which provides detailed information about the individual validation issues.
- Choose safeParse when a result object is preferable to exception-based control flow.
Common mistakes
- Invalid input raises a ZodError instead of returning a failure object; use safeParse when you want a non-throwing result.
- Schemas involving asynchronous refinements or transforms require parseAsync rather than parse.
Example: Parsing a player object
import { z } from "zod";
const Player = z.object({
username: z.string(),
xp: z.number(),
});
const player = Player.parse({ username: "billie", xp: 100 });
console.log(player.username);Validates the input and returns the parsed, strongly typed player value.
When to use it
Typed data extraction
Convert untrusted input into a schema-shaped value with inferred TypeScript types.
Exception-based validation
Fail immediately when required data does not satisfy a schema.
Interview questions
QWhat does Zod's parse method do?
parse validates unknown input against a schema. On success it returns a strongly typed deep clone; on failure it throws a ZodError.
Follow-up: How would you avoid exceptions for ordinary validation failures? Use safeParse, which returns an object containing either parsed data or a ZodError.
QWhat does parse return on successful validation?
The returned value is a deep clone of the input, so callers receive validated data without retaining the original object's identity.
Follow-up: Why might this matter for mutable objects? Mutating the parsed result does not mutate the original input object through shared nested references.
QWhen should parseAsync be used instead?
parse is synchronous and cannot complete asynchronous refinements or transforms. In those cases, parseAsync must be awaited.
Follow-up: What alternative handles asynchronous validation without throwing? safeParseAsync returns a result object for asynchronous success or failure.
Related
safeParseparseAsyncsafeParseAsyncZodError