Zod · Module

z.preprocess

z.preprocess() transforms raw input before passing it to another Zod schema for validation. It is useful for custom normalization or coercion, while straightforward primitive coercion can use Zod's dedicated coercion APIs.

How it works

z.preprocess() creates a schema that runs a preprocessing function on the input first, then feeds the result into the supplied schema for validation. Its input type is unknown by default because the function may receive arbitrary values; annotate the function parameter when you need a narrower input type.

Syntax

z.preprocess(preprocess, schema)

Parameters

Name	Type	Description
`preprocess`	`(value: unknown) => unknown`	Function that receives the raw input and returns the value to be parsed by the target schema.
`schema`	`z.ZodType`	Schema that validates the value returned by the preprocessing function.

Returns

A schema that preprocesses its input and then validates the resulting value with the supplied schema; in current Zod it is represented by a ZodPipe.

Key points

The API is a convenience for combining an input transform with a schema that validates the transformed value.
Write the preprocessing function defensively because it may receive values of any runtime type.
Use z.input to inspect or expose the input type accepted by a preprocessing schema.
Use z.output to inspect the type produced after preprocessing and validation.

Common mistakes

The inferred input type is unknown unless the preprocessor parameter is explicitly annotated.

Example: Preprocess input before validation

import { z } from "zod";

const coercedInt = z.preprocess((value) => {
  if (typeof value === "string") return Number.parseInt(value, 10);
  return value;
}, z.int());

console.log(coercedInt.parse("42")); // 42

The preprocessor converts string input to a number before the integer schema validates it.

When to use it

Pre-parse coercion

Convert form, query-string, or environment-variable values into a validated primitive.

Input normalization

Normalize nullable or loosely shaped input before applying a strict schema.

Input/output type separation

Accept a wider external input type while exposing a precise parsed output type.

Interview questions

QWhat does z.preprocess() do?

z.preprocess() applies a function before the destination schema parses the value. This is useful when input must be normalized or coerced before validation, such as converting a numeric string into an integer.

Follow-up: How can the input type be narrowed? Annotate the preprocessor parameter, then use z.input<typeof schema> to obtain the narrowed input type.

QWhat are the input and output types of a preprocessed schema?

The preprocessor receives arbitrary input by default, so the schema's input type is unknown. The output type comes from the schema passed as the second argument.

Follow-up: What are the corresponding type helpers? z.input<typeof schema> describes the accepted input, while z.output<typeof schema> describes the parsed result.

QWhen would you choose preprocessing?

It is useful when a transformation must happen before validation rather than after it. The transformed value is then checked by the target schema, such as z.int() in a string-to-number conversion.

Follow-up: When should primitive coercion be used instead? Use Zod's primitive coercion support for straightforward primitive conversions; reserve preprocessing for custom preparation logic.

z.coerce
z.pipe
z.transform
z.input
z.output

Source: Defining schemas | Zod. Checked 2026-10-15.