Calling `withStructuredOutput` with schema modifies schema and removes `transform()` configurations

[ro0sterjam]

Checked other resources

• This is a bug, not a usage question. For questions, please use the LangChain Forum (https://forum.langchain.com/).
• I added a very descriptive title to this issue.
• I searched the LangChain.js documentation with the integrated search.
• I used the GitHub search to find a similar question and didn't find it.
• I am sure that this is a bug in LangChain.js rather than my code.
• The bug is not resolved by updating to the latest stable version of LangChain (or the specific integration package).

Example Code

import { ChatPromptTemplate } from "@langchain/core/prompts";
import { ChatOpenAI } from "@langchain/openai";
import { z } from "zod/v4";

const schema = z.object({
  message: z.string().transform((x) => x.toUpperCase()),
});

const schemaUntouched = z.object({
  message: z.string().transform((x) => x.toUpperCase()),
});

const chatbot = new ChatOpenAI({ temperature: 0 });

const messages = ["Hello"];
const prompt = await ChatPromptTemplate.fromMessages(messages);

console.log(JSON.stringify(schema) === JSON.stringify(schemaUntouched)); // logs true

const chatbotWithStructuredOutput = chatbot.withStructuredOutput(schema, {
  includeRaw: true,
});

console.log(JSON.stringify(schema) === JSON.stringify(schemaUntouched)); // logs false

const runnable = prompt.pipe(chatbotWithStructuredOutput);
const result = await runnable.invoke({});

console.log(schema.parse(result.parsed)); // Logs { message: 'Hello' }
console.log(schemaUntouched.parse(result.parsed)); // Logs { message: 'HELLO' }

Error Message and Stack Trace (if applicable)

No response

Description

When I pass a schema to withStructuredOutput, it appears to modify the schema itself, in my particular case it is removing any transform() methods I have configured on the schema.

The example demonstrates that calling parse from the passed in schema does not perform the transform, but calling parsed on the untouched copy of the schema does.

Additionally you can see via the logs before and after calling withStructuredOutput that the schema is in fact mutated.

System Info

Langchain 0.3.35
Node v24.5.0
OSX 15.6.1 (24G90)

[ro0sterjam]

Okay I've narrowed it down to the internal call to interopZodTransformInputSchema where the definition is:

/**
 * Returns the input type of a Zod transform schema, for both v3 and v4.
 * If the schema is not a transform, returns undefined. If `recursive` is true,
 * recursively processes nested object schemas and arrays of object schemas.
 *
 * @param schema - The Zod schema instance (v3 or v4)
 * @param {boolean} [recursive=false] - Whether to recursively process nested objects/arrays.
 * @returns The input Zod schema of the transform, or undefined if not a transform
 */
export declare function interopZodTransformInputSchema(schema: InteropZodType, recursive?: boolean): InteropZodType;

But this method not only returns "the input Zod schema" of the transform but it actually modifies the transform completely (i.e. deletes it).

I don't know if this was the intended behaviour... but it is not ideal for my use case. Preferably, this function simply returns the new type without modifying the underlying input.

[ro0sterjam]

Here is the new updated test code that demonstrates the behaviour:

import { type InteropZodType, interopZodTransformInputSchema } from "@langchain/core/utils/types";
import { z } from "zod/v4";

const schema = z.object({
  message: z.string().transform((x) => x.toUpperCase()),
});

const schemaUntouched = z.object({
  message: z.string().transform((x) => x.toUpperCase()),
});

console.log(JSON.stringify(schema) === JSON.stringify(schemaUntouched)); // logs true
interopZodTransformInputSchema(schema as unknown as InteropZodType, true);
console.log(JSON.stringify(schema) === JSON.stringify(schemaUntouched)); // logs false

const message = { message: "hello" };

console.log(schema.parse(message)); // Logs { message: 'Hello' }
console.log(schemaUntouched.parse(message)); // Logs { message: 'HELLO' }

[ro0sterjam]

Perplexity suggests this rewritten version of the method that does not mutate the input:

export function interopZodTransformInputSchemaNew(schema, recursive = false) {
  if (isZodSchemaV3(schema)) {
    if (isZodTransformV3(schema)) {
      return interopZodTransformInputSchemaNew(schema._def.schema, recursive);
    }
    return schema;
  }

  if (isZodSchemaV4(schema)) {
    let outputSchema = schema;
    if (isZodTransformV4(schema)) {
      outputSchema = interopZodTransformInputSchemaNew(schema._zod.def.in, recursive);
    }
    if (recursive) {
      if (isZodObjectV4(outputSchema)) {
        // Create a new shape object without mutating original shape
        const originalShape = outputSchema._zod.def.shape;
        const newShape = {};
        for (const [key, keySchema] of Object.entries(originalShape)) {
          newShape[key] = interopZodTransformInputSchemaNew(keySchema, recursive);
        }
        outputSchema = clone(outputSchema, {
          ...outputSchema._zod.def,
          shape: newShape,
        });
      } else if (isZodArrayV4(outputSchema)) {
        const newElement = interopZodTransformInputSchemaNew(
          outputSchema._zod.def.element,
          recursive,
        );
        outputSchema = clone(outputSchema, {
          ...outputSchema._zod.def,
          element: newElement,
        });
      }
    }
    const meta = globalRegistry.get(schema);
    if (meta) globalRegistry.add(outputSchema, meta);
    return outputSchema;
  }

  throw new Error("Schema must be an instance of z3.ZodType or z4.$ZodType");
}

I have not yet looked over the code to verify its correctness, but some simple testing seems correct.

import {
  type InteropZodType,
  interopZodTransformInputSchema,
  interopZodTransformInputSchemaNew,
} from "@langchain/core/utils/types";
import { z } from "zod/v4";

const schema = z.object({
  message: z.string().transform((x) => x.toUpperCase()),
});

const schemaNew = z.object({
  message: z.string().transform((x) => x.toUpperCase()),
});

const schemaUntouched = z.object({
  message: z.string().transform((x) => x.toUpperCase()),
});

console.log(JSON.stringify(schema) === JSON.stringify(schemaUntouched)); // logs true
const out = interopZodTransformInputSchema(schema as unknown as InteropZodType, true);
console.log(JSON.stringify(schema) === JSON.stringify(schemaUntouched)); // logs false

console.log(JSON.stringify(schemaNew) === JSON.stringify(schemaUntouched)); // logs true
const outNew = interopZodTransformInputSchemaNew(schemaNew as unknown as InteropZodType, true);
console.log(JSON.stringify(schemaNew) === JSON.stringify(schemaUntouched)); // logs true

console.log(JSON.stringify(out) === JSON.stringify(outNew)); // logs true

const message = { message: "hello" };

console.log(schema.parse(message)); // Logs { message: 'Hello' }
console.log(schemaNew.parse(message)); // Logs { message: 'HELLO' }
console.log(schemaUntouched.parse(message)); // Logs { message: 'HELLO' }

[hntrl]

Oh interesting, yeah this definitely isn't intended. We drop the transformations because in the step where we serialize a zod schema to json schema (since this is what providers are expecting) we want the input side of the schema so we can apply the transformations on the model output at runtime.

[ro0sterjam]

Oh interesting, yeah this definitely isn't intended. We drop the transformations because in the step where we serialize a zod schema to json schema (since this is what providers are expecting) we want the input side of the schema so we can apply the transformations on the model output at runtime.

Yeah that makes sense.

I tried to simply replace the existing interopZodTransformInputSchema with the A.I. generated pure version, but then the OpenAI chat model started complaining that transforms were not allowed.

I think some part of the codebase takes advantage of the fact that interopZodTransformInputSchema modifies the input, so it won't be as easy as simply changing this method.

[ro0sterjam]

Incidentally, I've noticed that the transform methods are not being stripped when wrapped behind an optional array (though, not when simply under a non optional array).

import { type InteropZodType, interopZodTransformInputSchema } from "@langchain/core/utils/types";
import { z } from "zod/v4";

const schemaWithOptional = z.object({
  messages: z.array(z.string().transform((x) => x.toUpperCase())).optional(),
});

const schemaWithoutOptional = z.object({
  messages: z.array(z.string().transform((x) => x.toUpperCase())),
});

interopZodTransformInputSchema(schemaWithOptional as unknown as InteropZodType, true);
interopZodTransformInputSchema(schemaWithoutOptional as unknown as InteropZodType, true);

const message = { messages: ["hello"] };

console.log(schemaWithOptional.parse(message)); // Logs { message: [ 'HELLO' ] }
console.log(schemaWithoutOptional.parse(message)); // Logs { message: [ 'hello' ] }

This failure to strip the transform results in error that you alluded to:

"message": "Transforms cannot be represented in JSON Schema"

Would it make sense to open another issue for this, or leave it as part of this issue?

---

Edit: Transform is also not stripped in the following examples:

const schemaArrayWithOptional = z.object({
  messages: z.array(z.string().transform((x) => x.toUpperCase())).optional(),
});

const schemaArrayWithOutsideOptional = z
  .object({
    messages: z.array(z.string().transform((x) => x.toUpperCase())),
  })
  .optional();

const schemaObjectWithOptional = z
  .object({
    message: z.string().transform((x) => x.toUpperCase()),
  })
  .optional();

Basically whenever optional is involved in some way or another.

---

Edit 2:

Assuming we keep the same mutating behaviour of the original interopZodTransformInputSchema, it should be as relatively simple as adding the following check in interopZodTransformInputSchema:

      if (outputSchema._zod.def.type === "optional") {
        outputSchema.def.innerType = interopZodTransformInputSchema(
          outputSchema.def.innerType,
          recursive,
        );
      }

I'll just go ahead and open a separate issue for this.

#9120