Make z.preprocess defer optionality to inner schema (#5929)

* Make z.preprocess defer optionality to inner schema (#5917)

`z.preprocess(fn, schema)` desugared to `pipe(transform(fn), schema)`,
so the resulting pipe's `optin` was inherited from `ZodTransform`
(undefined) instead of from the inner schema. When the inner schema was
itself optional and the preprocess sat as an object property, the
object compiler took the `!isOptionalIn` branch and synthesized a
`nonoptional` issue for missing keys — making the position of
`.optional()` change presence semantics.

Introduce `ZodPreprocess` as a structural subtype of `ZodPipe` (same
`def.type === "pipe"`, `instanceof ZodPipe` still true). It pins
`def.in` to a permissive `z.unknown()` and re-installs the four lazy
metadata props so `optin`, `optout`, `values`, and `propValues` all
defer to `def.out` (the inner schema). Backward direction throws,
matching today's behavior.

The two JSON-schema sites that special-cased the old
`pipe(transform, ...)` shape (`pipeProcessor` and `isTransforming`)
now also detect preprocess via `_zod.traits`.

* Stop deferring values/propValues from inner schema

`values` and `propValues` describe the *input* set a schema accepts.
Preprocess opens that set to anything `fn` can map to a B-accepted
value, so deferring these to B was unsound:

- discriminated unions use `propValues` as a fast-path disc map; with
  B's propValues exposed, an option claims to match only B's literal
  inputs and silently routes wrong (e.g. preprocess(toUpperCase,
  z.literal("A")) would fail to match input "a"). Now reverts to
  throwing at construction, matching pre-PR behavior.
- `z.record()` uses `values` to enumerate expected keys; with B's
  values exposed it short-circuits before the preprocess fn ever runs
  on input keys.

Presence semantics (`optin`/`optout`) describe whether the *outer*
container can omit this slot; preprocess is transparent to those, so
they continue to defer to B (the original #5917 fix).

* Add type-level tests for ZodPreprocess assignability

Document the invariant that ZodPreprocess<B> is structurally
assignable to ZodPipe<$ZodType, B>, and that the optin/optout
override surfaces B's declared type (narrowed for schemas like
ZodOptional that hardcode it, open `"optional" | undefined` for
schemas like ZodString that inherit it).

* Use traits.has consistently in pipeProcessor

`pipeProcessor` was mixing detection styles: `traits.has("$ZodPreprocess")`
for the new subtype and `def.in._zod.def.type === "transform"` for the
legacy pipe(transform, ...) form. Both check "input contributes no
validation, use B for input-side JSON schema." Converge on traits.

* Treat ZodCodec as transforming for JSON schema example/default stripping

Same diagnosis as the preprocess case: `isTransforming` recurses into
`def.in` and `def.out` looking for `def.type === "transform"`, but
`ZodCodec` embeds an implicit transform fn (its `decode`/`encode`)
while `def.in` and `def.out` are validating schemas. The recursion
finds no transform and returns false even though the codec absolutely
is transforming, causing output-side examples/defaults to leak into
the input JSON schema.

Detect via `_zod.traits.has("$ZodCodec")` alongside the preprocess
check.

* Document ZodPreprocess in inheritance hierarchy

Surface ZodPreprocess everywhere the codebase enumerates first-party
types as a structural sibling of ZodCodec under ZodPipe:

- core.mdx: $ZodTypes union comment ("$ZodCodec and $ZodPreprocess
  extend this") and the inheritance diagram
- assignability.test.ts: explicit `satisfies` checks confirming the
  type-level relationship to $ZodPreprocess and $ZodPipe (with
  generics specified — the bare-generic form bites variance because
  inherited reverseTransform is contravariant in B)

The $ZodTypes union itself doesn't need a new entry — preprocess is
covered transitively via $ZodPipe, same as $ZodCodec — but documenting
the relationship in prose and tests makes the hierarchy discoverable.

* Simplify ZodPreprocess to a pure metadata-override subtype

The bug is purely a static-metadata problem: $ZodPipeInternals.optin
was inheriting from A (the leading transform, which has no optin)
instead of from B (the inner schema). The runtime parse path for
pipe(transform(fn), schema) was already correct.

So the simpler design is: keep the runtime structure exactly as the
legacy form (def.in is a real ZodTransform), and just override the
optin/optout lazies in a thin subtype.

What this eliminates from the previous design:

- Custom parse function in $ZodPreprocess.init (forward direction with
  embedded transform fn)
- Custom parse function in classic ZodPreprocess.init (addIssue
  injection — the inner ZodTransform's classic parse override already
  does this)
- The synthetic z.unknown() input slot
- The required `transform` field on the def
- traits.has("$ZodPreprocess") check in pipeProcessor and
  isTransforming — def.in is a real ZodTransform, so the existing
  detection paths fire correctly

The traits.has("$ZodCodec") check in isTransforming stays — codec
embeds its transform fn directly on the def (different shape) and
needs its own detection.

* Trim verbose comments to match house style

Author: colinhacks

packages/docs/content/packages/core.mdx

@@ -84,7 +84,7 @@ export type $ZodTypes =
   | $ZodNonOptional
   | $ZodReadonly
   | $ZodNaN
-  | $ZodPipe // $ZodCodec extends this
+  | $ZodPipe // $ZodCodec and $ZodPreprocess extend this
   | $ZodSuccess
   | $ZodCatch
   | $ZodFile;
@@ -156,6 +156,7 @@ export type $ZodTypes =
       - $ZodNaN
       - $ZodPipe
           - $ZodCodec
+          - $ZodPreprocess
       - $ZodReadonly
       - $ZodTemplateLiteral
       - $ZodCustom

packages/zod/src/v4/classic/schemas.ts

@@ -2361,6 +2361,22 @@ export function invertCodec<A extends core.SomeType, B extends core.SomeType>(co
   }) as any;
 }
 
+// ZodPreprocess
+export interface ZodPreprocess<B extends core.SomeType = core.$ZodType>
+  extends ZodPipe<core.$ZodTransform, B>,
+    core.$ZodPreprocess<B> {
+  "~standard": ZodStandardSchemaWithJSON<this>;
+  _zod: core.$ZodPreprocessInternals<B>;
+  def: core.$ZodPreprocessDef<B>;
+}
+export const ZodPreprocess: core.$constructor<ZodPreprocess> = /*@__PURE__*/ core.$constructor(
+  "ZodPreprocess",
+  (inst, def) => {
+    ZodPipe.init(inst, def);
+    core.$ZodPreprocess.init(inst, def);
+  }
+);
+
 // ZodReadonly
 export interface ZodReadonly<T extends core.SomeType = core.$ZodType>
   extends _ZodType<core.$ZodReadonlyInternals<T>>,
@@ -2645,6 +2661,10 @@ export function json(params?: string | core.$ZodCustomParams): ZodJSONSchema {
 export function preprocess<A, U extends core.SomeType, B = unknown>(
   fn: (arg: B, ctx: core.$RefinementCtx) => A,
   schema: U
-): ZodPipe<ZodTransform<A, B>, U> {
-  return pipe(transform(fn as any), schema as any) as any;
+): ZodPreprocess<U> {
+  return new ZodPreprocess({
+    type: "pipe",
+    in: transform(fn as any) as any as core.$ZodTransform,
+    out: schema as any as core.$ZodType,
+  }) as any;
 }

packages/zod/src/v4/classic/tests/assignability.test.ts

@@ -143,6 +143,12 @@ test("assignability", () => {
   z.unknown().pipe(z.number()) satisfies z.core.$ZodPipe;
   z.unknown().pipe(z.number()) satisfies z.ZodPipe;
 
+  // $ZodPreprocess
+  z.preprocess((v) => v, z.number()) satisfies z.core.$ZodPreprocess;
+  z.preprocess((v) => v, z.number()) satisfies z.ZodPreprocess;
+  z.preprocess((v) => v, z.number()) satisfies z.core.$ZodPipe<z.core.$ZodTransform, z.ZodNumber>;
+  z.preprocess((v) => v, z.number()) satisfies z.ZodPipe<z.core.$ZodTransform, z.ZodNumber>;
+
   // $ZodSuccess
   z.success(z.string()) satisfies z.core.$ZodSuccess;
   z.success(z.string()) satisfies z.ZodSuccess;

packages/zod/src/v4/classic/tests/preprocess-types.test.ts

@@ -0,0 +1,26 @@
+import { expectTypeOf, test } from "vitest";
+import * as z from "zod/v4";
+
+test("ZodPreprocess<B> assignable to ZodPipe<$ZodTransform, B>", () => {
+  const pre = z.preprocess((v) => v, z.string().optional());
+  const _asPipe: z.ZodPipe<z.core.$ZodTransform, z.ZodOptional<z.ZodString>> = pre;
+  const _asCorePipe: z.core.$ZodPipe<z.core.$ZodTransform, z.ZodOptional<z.ZodString>> = pre;
+  expectTypeOf(_asPipe).toMatchTypeOf<z.ZodPipe>();
+  expectTypeOf(_asCorePipe).toMatchTypeOf<z.core.$ZodPipe>();
+});
+
+test("ZodPreprocess optin/optout defer to B", () => {
+  const optionalInside = z.preprocess((v) => v, z.string().optional());
+  expectTypeOf<(typeof optionalInside)["_zod"]["optin"]>().toEqualTypeOf<"optional">();
+  expectTypeOf<(typeof optionalInside)["_zod"]["optout"]>().toEqualTypeOf<"optional">();
+
+  const required = z.preprocess((v) => v, z.string());
+  expectTypeOf<(typeof required)["_zod"]["optin"]>().toEqualTypeOf<"optional" | undefined>();
+  expectTypeOf<(typeof required)["_zod"]["optout"]>().toEqualTypeOf<"optional" | undefined>();
+});
+
+test("ZodPreprocess input/output inference", () => {
+  const pre = z.preprocess((v) => v, z.number().optional());
+  expectTypeOf<z.output<typeof pre>>().toEqualTypeOf<number | undefined>();
+  expectTypeOf<z.input<typeof pre>>().toEqualTypeOf<unknown>();
+});

packages/zod/src/v4/classic/tests/preprocess.test.ts

@@ -280,3 +280,47 @@ test("perform transform with non-fatal issues", () => {
     ]]
   `);
 });
+
+// https://github.com/colinhacks/zod/issues/5917
+test("optional propagates through preprocess inside object", () => {
+  const outer = z.object({ x: z.preprocess((v) => v, z.number()).optional() });
+  const inner = z.object({ x: z.preprocess((v) => v, z.number().optional()) });
+
+  expect(outer.safeParse({}).success).toBe(true);
+  expect(inner.safeParse({}).success).toBe(true);
+
+  expect(outer.safeParse({ x: 1 })).toEqual({ success: true, data: { x: 1 } });
+  expect(inner.safeParse({ x: 1 })).toEqual({ success: true, data: { x: 1 } });
+
+  expect(inner._zod.def.shape.x._zod.optin).toBe("optional");
+  expect(inner._zod.def.shape.x._zod.optout).toBe("optional");
+});
+
+test("preprocess is a structural subtype of ZodPipe", () => {
+  const schema = z.preprocess((v) => v, z.string());
+  expect(schema).toBeInstanceOf(z.ZodPipe);
+  expect(schema).toBeInstanceOf(z.ZodPreprocess);
+  expect(schema._zod.def.type).toBe("pipe");
+});
+
+test("preprocess does not propagate values/propValues from inner schema", () => {
+  const inner = z.preprocess((v) => v, z.literal("test"));
+  expect(inner._zod.values).toBeUndefined();
+  expect(inner._zod.propValues).toBeUndefined();
+});
+
+test("preprocess as discriminator throws at construction (no propValues to inherit)", () => {
+  const schema = z.discriminatedUnion("kind", [
+    z.object({ kind: z.preprocess((v: any) => String(v).toUpperCase(), z.literal("A")), a: z.string() }),
+    z.object({ kind: z.preprocess((v: any) => String(v).toUpperCase(), z.literal("B")), b: z.number() }),
+  ]);
+  expect(() => schema.parse({ kind: "a", a: "x" })).toThrow(/Invalid discriminated union option/);
+});
+
+test("preprocess as record key does not restrict accepted keys", () => {
+  const schema = z.record(
+    z.preprocess((v: any) => String(v).toLowerCase(), z.enum(["a", "b"])),
+    z.string()
+  );
+  expect(schema.safeParse({ A: "x", B: "y" })).toEqual({ success: true, data: { a: "x", b: "y" } });
+});

packages/zod/src/v4/classic/tests/to-json-schema.test.ts

@@ -2896,6 +2896,28 @@ test("use output type for preprocess", () => {
   `);
 });
 
+test("strip output-side examples from input JSON schema for codec", () => {
+  const codec = z
+    .codec(z.string(), z.number(), { decode: (s) => Number(s), encode: (n) => String(n) })
+    .meta({ examples: [42] });
+
+  expect(z.toJSONSchema(codec, { io: "input" })).toMatchInlineSnapshot(`
+    {
+      "$schema": "https://json-schema.org/draft/2020-12/schema",
+      "type": "string",
+    }
+  `);
+  expect(z.toJSONSchema(codec, { io: "output" })).toMatchInlineSnapshot(`
+    {
+      "$schema": "https://json-schema.org/draft/2020-12/schema",
+      "examples": [
+        42,
+      ],
+      "type": "number",
+    }
+  `);
+});
+
 // test("isTransforming", () => {
 //   const tx = z.core.isTransforming;
 //   expect(tx(z.string())).toEqual(false);

packages/zod/src/v4/core/json-schema-processors.ts

@@ -525,7 +525,8 @@ export const catchProcessor: Processor<schemas.$ZodCatch> = (schema, ctx, json,
 
 export const pipeProcessor: Processor<schemas.$ZodPipe> = (schema, ctx, _json, params) => {
   const def = schema._zod.def as schemas.$ZodPipeDef;
-  const innerType = ctx.io === "input" ? (def.in._zod.def.type === "transform" ? def.out : def.in) : def.out;
+  const inIsTransform = def.in._zod.traits.has("$ZodTransform");
+  const innerType = ctx.io === "input" ? (inIsTransform ? def.out : def.in) : def.out;
   process(innerType, ctx as any, params);
   const seen = ctx.seen.get(schema)!;
   seen.ref = innerType;

packages/zod/src/v4/core/schemas.ts

@@ -4118,6 +4118,37 @@ function handleCodecTxResult(left: ParsePayload, value: any, nextSchema: SomeTyp
   return nextSchema._zod.run({ value, issues: left.issues }, ctx);
 }
 
+/////////////////////////////////////////////////
+/////////////////////////////////////////////////
+//////////                             //////////
+//////////      $ZodPreprocess         //////////
+//////////                             //////////
+/////////////////////////////////////////////////
+/////////////////////////////////////////////////
+export interface $ZodPreprocessDef<B extends SomeType = $ZodType> extends $ZodPipeDef<$ZodTransform, B> {
+  in: $ZodTransform;
+  out: B;
+}
+
+export interface $ZodPreprocessInternals<B extends SomeType = $ZodType> extends $ZodPipeInternals<$ZodTransform, B> {
+  def: $ZodPreprocessDef<B>;
+  optin: B["_zod"]["optin"];
+  optout: B["_zod"]["optout"];
+}
+
+export interface $ZodPreprocess<B extends SomeType = $ZodType> extends $ZodPipe<$ZodTransform, B> {
+  _zod: $ZodPreprocessInternals<B>;
+}
+
+export const $ZodPreprocess: core.$constructor<$ZodPreprocess> = /*@__PURE__*/ core.$constructor(
+  "$ZodPreprocess",
+  (inst, def) => {
+    $ZodPipe.init(inst, def);
+    util.defineLazy(inst._zod, "optin", () => def.out._zod.optin);
+    util.defineLazy(inst._zod, "optout", () => def.out._zod.optout);
+  }
+);
+
 ////////////////////////////////////////////
 ////////////////////////////////////////////
 //////////                        //////////

packages/zod/src/v4/core/to-json-schema.ts

@@ -561,6 +561,7 @@ function isTransforming(
     return isTransforming(def.keyType, ctx) || isTransforming(def.valueType, ctx);
   }
   if (def.type === "pipe") {
+    if (_schema._zod.traits.has("$ZodCodec")) return true;
     return isTransforming(def.in, ctx) || isTransforming(def.out, ctx);
   }