This page documents Zod's schema transformation capabilities, which allow you to modify, compose, and transform schemas and their data. These features enable custom validation logic, value transformation, schema combination, and default value handling.
Related pages: For basic schema type definitions, see Schema Types and Validation. For details on specific transformation methods, see Refinements and Custom Validation, Transformations and Preprocessing, Schema Composition, Codecs and Bidirectional Transforms, and Default and Prefault Values.
Scope: This page provides an overview of transformation mechanisms. Child pages provide detailed documentation on each category.
Zod provides five main categories of schema transformations:
Sources: README.md124-131 packages/zod/src/v4/classic/tests/index.test.ts469-543 packages/zod/src/v4/classic/tests/object.test.ts319-329
Transformations integrate into Zod's validation pipeline at specific points:
Key characteristics:
| Stage | Timing | Abortable | Type Change | Use Case |
|---|---|---|---|---|
| Prefault | Before validation | No | No | Supply missing input values |
| Type Check | First | Yes (implicit) | No | Verify base type |
| Constraint Checks | Early | Configurable | No | Built-in validations |
| Refinements | Mid | Configurable | No | Custom validation logic |
| Transforms | Late | No | Yes | Modify/convert values |
| Default | After validation | No | No | Supply missing output values |
Sources: packages/zod/src/v4/core/util.ts804-824 packages/zod/src/v4/classic/tests/default.test.ts116-235 README.md124-180
Sources: packages/zod/src/v4/classic/tests/object.test.ts319-450 packages/zod/src/v4/classic/tests/index.test.ts469-560 packages/zod/src/v4/core/util.ts485-799
Zod provides multiple ways to combine and modify schemas:
| Method | Restrictions | Preserves Refinements | Creates New Instance | Use Case |
|---|---|---|---|---|
.extend(shape) | Throws on overlap w/ refinements | Yes | Yes | Add new properties |
.safeExtend(shape) | None | Yes | Yes | Override properties safely |
.merge(other) | None | No | Yes | Combine two object schemas |
.pick(mask) | No refinements | N/A | Yes | Select specific keys |
.omit(mask) | No refinements | N/A | Yes | Remove specific keys |
.partial(mask?) | No refinements | N/A | Yes | Make keys optional |
.required(mask?) | None | Yes | Yes | Make keys required |
.intersection(a, b) | None | Yes | Yes | Require both schemas |
.union([a, b]) | None | Yes | Yes | Accept either schema |
.pipe(schema) | None | Yes | Yes | Sequential validation |
Sources: packages/zod/src/v4/classic/tests/object.test.ts408-641 packages/zod/src/v4/classic/tests/pickomit.test.ts138-211 packages/zod/src/v4/core/tests/extend.test.ts1-60
Sources: packages/zod/src/v4/classic/tests/object.test.ts605-640 packages/zod/src/v4/core/tests/extend.test.ts4-18
Transformations can change input and output types:
Sources: packages/zod/src/v4/classic/tests/index.test.ts469-502 README.md198-208
Sources: packages/zod/src/v4/classic/tests/index.test.ts469-502 README.md198-208
Some transformations behave differently based on direction (parse vs encode):
Key differences:
| Feature | Forward (Parse) | Reverse (Encode) | Why? |
|---|---|---|---|
.default() | Applied | NOT applied | Defaults fill missing inputs, not outputs |
.prefault() | Applied | NOT applied | Prefaults fill missing inputs, not outputs |
.catch() | Applied | Applied | Error handling works both ways |
.transform() | Applied | Reversed (if codec) | Value transformations are directional |
Sources: packages/zod/src/v4/classic/tests/default.test.ts335-365 packages/zod/src/v4/classic/tests/prefault.test.ts51-74
Sources: packages/zod/src/v4/classic/tests/default.test.ts335-365
Refinements support abort flags to control validation flow:
Abort behavior:
continue: false - Explicit abort (most checks)continue: undefined - Implicit abort (default)continue: true - Continue collecting issues (rare)Sources: packages/zod/src/v4/core/util.ts804-824
Object schemas have specialized transformation methods:
Sources: packages/zod/src/v4/classic/tests/object.test.ts279-313 packages/zod/src/v4/classic/tests/pickomit.test.ts1-92
Sources: packages/zod/src/v4/classic/tests/object.test.ts213-218 packages/zod/src/v4/core/tests/extend.test.ts20-59
Zod provides three mechanisms for handling missing values:
| Method | Applied When | Direction | Failure Behavior | Use Case |
|---|---|---|---|---|
.default(val) | undefined input | Forward only | N/A | Supply output defaults |
.prefault(val) | undefined input | Forward only | N/A | Supply input defaults |
.catch(val) | Validation fails | Both | Catches errors | Error recovery |
Sources: packages/zod/src/v4/classic/tests/default.test.ts116-235 packages/zod/src/v4/classic/tests/prefault.test.ts1-14
Defaults in object schemas affect optionality:
Sources: packages/zod/src/v4/classic/tests/default.test.ts83-95 packages/zod/src/v4/classic/tests/default.test.ts103-114
The .pipe() method chains schemas sequentially:
Usage:
Sources: packages/zod/src/v4/classic/tests/index.test.ts571-587
All transformation methods return new schema instances:
The clone() utility function creates schema copies:
Sources: packages/zod/src/v4/core/util.ts485-489 README.md86
Transformations use cloneDef() and mergeDefs() to create modified schemas:
Sources: packages/zod/src/v4/core/util.ts308-321
Shape manipulation methods create new shape objects with lazy evaluation:
Sources: packages/zod/src/v4/core/util.ts593-620
Transformations work with recursive schemas using getter properties:
Sources: packages/zod/src/v4/classic/tests/recursive-types.test.ts122-149 packages/zod/src/v4/classic/tests/recursive-types.test.ts302-367
Zod's transformation system provides comprehensive tools for:
.refine() and .superRefine().transform() and .preprocess().extend(), .merge(), .pipe().pick(), .omit(), .partial(), .required().prefault() and .default()All transformations are immutable, returning new schema instances while preserving the original. Direction-aware operations (defaults, prefaults) behave differently in forward (parse) vs reverse (encode) operations, enabling bidirectional schema usage with codecs.
Sources: README.md58-209 packages/zod/src/v4/core/util.ts485-799 packages/zod/src/v4/classic/tests/object.test.ts1-641
Refresh this wiki