`.pipe` seems arbitrarily restricted in V4

[ConnorSinnott]

Hello! I'm in the process of migrating to v4 and the largest headache so far has been the changes to .pipe. From what I'm gathering from errors, whatever schema is being piped to must have the input match the output of the source schema.

For my specific example, I had a JSON parsing schema which accepts a string and parses the result as JSON returning an object. I'd then pipe that into whatever schema I needed that object to match. This doesn't appear to be supported anymore since the input requirement for pipe can not be determined.

import { z } from 'zod/v4';

export const someStringSchema = z.string();

const someObjectSchema: z.ZodSchema = z.object({ // Arbitrarily erasing the inferred type to be just ZodSchema
  name: z.string(),
})

someStringSchema.pipe(someObjectSchema).parse({}) 
// Types of property _zod are incompatible.
// Type $ZodTypeInternals<unknown, unknown> is not assignable to type $ZodTypeInternals<any, string>
// Type unknown is not assignable to type string

I can apparently calm the linter by defining z.ZodSchema<any, any>

import { z } from 'zod/v4';

export const someStringSchema = z.string();

const someObjectSchema: z.ZodSchema<any, any> = z.object({
  name: z.string(),
})

someStringSchema.pipe(someObjectSchema).parse({}) // No issues

I guess I can see why perhaps a developer would want to be warned that they are piping an incompatible type, but this seems to hinder abstract Zod work.

Any suggestions?

[dosubot]

Hi @ConnorSinnott! I'm Dosu and I’m helping the zod team.

You're right—Zod v4 made .pipe much stricter: the output type of the first schema must match the input type of the next. This was intentional to fix unsoundness in v3, where transformations could break type safety (for example, discriminated unions relying on post-transform values, which could cause runtime errors) [source].

For your JSON parsing use case, the best practice in v4 is to use z.preprocess or z.transform to handle the parsing, then validate the result. In fact, z.preprocess(fn, schema) is now just syntactic sugar for z.pipe(z.transform(fn), schema) [source]. Here’s how you might do it:

import { z } from "zod";

const parseJson = (val: unknown) => {
  if (typeof val === "string") {
    try {
      return JSON.parse(val);
    } catch {
      return undefined;
    }
  }
  return val;
};

const schema = z
  .string()
  .transform(parseJson)
  .pipe(z.object({ name: z.string() }));

// or, equivalently:
const schema2 = z.preprocess(parseJson, z.object({ name: z.string() }));

If you need to compose schemas more abstractly and want to suppress type errors, you can use ZodSchema<any, any>, but this disables type safety and is not recommended unless you have a strong reason [source].

For custom refinements where you want to keep type inference, you can use z.custom<Type>() and then .pipe() [source].

If you have a more complex use case or need to compose schemas dynamically, let me know with a minimal example and I can suggest a more tailored workaround.

If this answers your question, please close the issue!

To reply, just mention @dosu.

---

Docs are dead. Just use Dosu.

[ConnorSinnott]

@dosu maybe I'm missing that the answer truly is to use anys. What is the recommended way to solve this pattern?

export const stringToJSONSchema = z.string().transform((str, ctx): Json => {
  try {
    return JSON.parse(str) as Json;
  } catch {
    ctx.addIssue({ code: 'custom', message: 'Invalid JSON' });
    return z.NEVER;
  }
});

export interface IEventHandler<Params> {
  get eventSchema(): z.ZodSchema<Params>;

  handleEvent(params: Params): Promise<...>;
}

type TestObj = {
  name: string;
};

class Test implements IEventHandler<TestObj> {
  get eventSchema(): z.ZodSchema<TestObj> {
    return z.object({
      name: z.string(),
    });
  }
}

const handler = new Test();

const data = stringToJSONSchema
  .pipe(handler.eventSchema) // Types of property _zod are incompatible.
  .parse('{"name": "test"}');

[dosubot]

You're not missing anything—this is a real limitation of Zod v4's .pipe. The type error happens because .pipe enforces that the output type of the first schema must exactly match the input type of the next, and Zod can't guarantee this for a generic/dynamic schema like your eventSchema getter. This is intentional to prevent unsoundness in type transformations, especially after issues in v3 with unsafe pipelines [source].

There isn't a fully type-safe way to compose a transform schema with a dynamically-typed schema via .pipe without erasing types (using any). The only built-in workaround is to explicitly use ZodSchema<any, any>, but this disables type safety and is not generally recommended unless you really need the flexibility [source].

If you want to keep as much type safety as possible, the recommended pattern is to use a function that takes the dynamic schema as an argument and builds the pipeline inline, like this:

function parseEvent<T>(handler: IEventHandler<T>, input: string): T {
  // Use .preprocess or .transform to parse JSON, then validate with the dynamic schema
  return z.preprocess(
    (str) => {
      try {
        return JSON.parse(str as string);
      } catch {
        return undefined;
      }
    },
    handler.eventSchema // This works because preprocess expects a ZodType
  ).parse(input);
}

This avoids .pipe entirely and leverages z.preprocess, which is just syntactic sugar for z.pipe(z.transform(fn), schema) but is more forgiving with dynamic schemas [source].

If you absolutely need to use .pipe for some reason, you can cast the schema as ZodSchema<any, any>, but you'll lose type safety:

const data = stringToJSONSchema
  .pipe(handler.eventSchema as z.ZodSchema<any, any>)
  .parse('{"name": "test"}');

But again, this is not recommended unless you have no other option.

Let me know if you have a more advanced use case or need a different workaround! If this solves your problem, feel free to close the issue.

To reply, just mention @dosu.

---

Share context across your team and agents. Try Dosu.

[ConnorSinnott]

Ok, the function dosu's written has pointed in me in the right direction. However, by performing the parse immediately we've removed the ability for someone to choose parse vs safeparse. So from what I've gathered here... the two code blocks below behave similarly.

// Zod V3
export const stringToJSONSchema = z.string().transform((str, ctx): Json => {
  try {
    return JSON.parse(str) as Json;
  } catch {
    ctx.addIssue({ code: 'custom', message: 'Invalid JSON' });
    return z.NEVER;
  }
});

const data = stringToJSONSchema.pipe(this.handler.eventSchema).parse(input);

// Zod V4
export function makeEventParser<T>(schema: z.ZodSchema<T>) {
  return z.string().pipe(z.preprocess(
    (str, ctx) => {
      try {
        return JSON.parse(str);
      } catch {
        ctx.addIssue({ code: 'custom', message: 'Invalid JSON' });
        return z.NEVER;
      }
    },
    schema,
  ))
}

const data = makeEventParser(this.handler.eventSchema).parse(input)

If any human happens upon this thread with any comments or suggestions for the differences I've highlighted here, I'd be happy to hear them.

[ConnorSinnott]

I've found just now that having the transform return unknown solves this as well.

export const stringToJSONSchema = z.string().transform((str, ctx): unknown => {
  try {
    return JSON.parse(str) as unknown;
  } catch {
    ctx.addIssue({ code: 'custom', message: 'Invalid JSON' });
    return z.NEVER;
  }
});

const data = stringToJSONSchema.pipe(this.handler.eventSchema).parse(input);

[pspeter3]

I returning unknown from transform the recommended solution?