Transformations and Preprocessing

Relevant source files

• packages/docs/content/api.mdx
• packages/docs/content/json-schema.mdx
• packages/docs/content/packages/core.mdx
• packages/zod/src/v4/classic/tests/assignability.test.ts
• packages/zod/src/v4/classic/tests/preprocess-types.test.ts
• packages/zod/src/v4/classic/tests/preprocess.test.ts
• packages/zod/src/v4/classic/tests/transform.test.ts
• packages/zod/src/v4/core/json-schema-processors.ts
• wiki/optionality.md

This document covers Zod's data transformation and preprocessing capabilities, including type coercion, string transformations, custom transforms, and the preprocess utility. These features allow you to modify and convert data as it flows through your schemas, affecting both the runtime values and the inferred TypeScript types.

Overview

Zod provides several transformation mechanisms that operate at different stages of the validation pipeline. Preprocessing occurs before a schema's internal validation, while transformations typically occur after.

Transform Pipeline Flow

Sources: packages/docs/content/api.mdx28-90 packages/zod/src/v4/classic/tests/transform.test.ts194-217

Preprocessing

The z.preprocess() function allows you to transform the input data before it is passed to the underlying schema. In Zod v4, $ZodPreprocess is implemented as a subclass of $ZodPipe where the "input" side is a $ZodTransform packages/docs/content/packages/core.mdx157-159

Preprocessing Architecture

Optionality and Preprocessing

In Zod v4, z.preprocess affects the schema's optin signal. While the static input type remains required (unless the inner schema is optional), the runtime optin is set to "optional". This means z.object({ a: z.preprocess(fn, z.string()) }) will accept {} at runtime without a "missing key" error, passing undefined to the preprocessor wiki/optionality.md52-67

Preprocessing functions receive a context ctx that allows for manual issue reporting via ctx.addIssue() packages/zod/src/v4/classic/tests/preprocess.test.ts27-55 If z.NEVER is returned from a preprocessor, the validation is aborted for that node packages/zod/src/v4/classic/tests/preprocess.test.ts160-186

Sources: packages/zod/src/v4/classic/tests/preprocess.test.ts4-25 packages/docs/content/packages/core.mdx157-159 wiki/optionality.md52-67

Coercion and Type Conversion

Zod's coercion system automatically converts input values to the target type using JavaScript's built-in constructors. This is a specialized form of preprocessing that simplifies common type conversions.

Zod API	JavaScript Coercion	Input Type
z.coerce.string()	String(value)	unknown
z.coerce.number()	Number(value)	unknown
z.coerce.boolean()	Boolean(value)	unknown
z.coerce.bigint()	BigInt(value)	unknown
z.coerce.date()	new Date(value)	unknown

By default, coerced schemas have an input type of unknown, but this can be narrowed using generic parameters: z.coerce.string<string>() packages/docs/content/api.mdx93-107

Sources: packages/docs/content/api.mdx60-92 packages/docs/content/api.mdx93-107

String Transformations

Zod provides built-in string transformation methods. These are implemented as part of the ZodString class and modify the string value during the parsing lifecycle.

String Transform Methods

These transformations modify the data before further validation checks (like .min() or .regex()) are applied, ensuring that constraints are checked against the transformed value packages/docs/content/api.mdx220-239

Sources: packages/docs/content/api.mdx220-239 packages/docs/content/packages/core.mdx18

Custom Transformations (.transform)

The .transform() method creates a $ZodTransform instance. It allows for arbitrary logic to be applied to validated data, changing the output type of the schema while preserving the input type.

Transform Lifecycle

1. Validation: The base schema validates the input.
2. Short-circuit: If validation fails with "fatal" issues, the transform is skipped packages/zod/src/v4/classic/tests/transform.test.ts194-217
3. Execution: The transform function runs, receiving the validated data and a context object.
4. Issue Reporting: The transform can add new issues via ctx.addIssue() packages/zod/src/v4/classic/tests/transform.test.ts4-28

Type Inference

In Zod v4, $ZodTransform also signals optin: "optional" at runtime, allowing it to handle absent keys in objects by receiving undefined wiki/optionality.md59-64

Sources: packages/zod/src/v4/classic/tests/transform.test.ts4-28 packages/zod/src/v4/classic/tests/transform.test.ts163-175 wiki/optionality.md59-64

Integration with JSON Schema

Transformations affect how schemas are exported to external formats via z.toJSONSchema().

JSON Schema Transformation Handling

Because .transform() contains arbitrary JavaScript logic, it is considered "unrepresentable" in standard JSON Schema and will cause z.toJSONSchema() to throw an error unless the unrepresentable: "any" option is used packages/docs/content/json-schema.mdx205-235 For $ZodPipe (and by extension $ZodPreprocess), the io parameter determines whether the input or output schema is processed packages/docs/content/json-schema.mdx131-144

Sources: packages/docs/content/json-schema.mdx131-144 packages/docs/content/json-schema.mdx205-235 packages/zod/src/v4/core/json-schema-processors.ts218