Since upgrade to Zod v4, examples expects transformed type and not input type.

[JonathanCabezas]

Description

import { defaultEndpointsFactory } from "express-zod-api";
import z from "zod";

export const getProductEndpoint = defaultEndpointsFactory.build({
  method: "get",
  tag: "product",
  description: "Get a product by id.",
  input: z.object({
    product_id: z.string().transform(Number).pipe(z.number().int().min(0)).example("1"),
  }),
  output: z.object({
    product_id: z.number(),
  }),
  handler: async ({ input: { product_id } }) => {
    await new Promise(resolve => setTimeout(resolve, 1000));
    return { product_id };
  },
});

Expected

example("1") should be valid, here I get Argument of type 'string' is not assignable to parameter of type 'number'

Context

• express-zod-api version: 25.4.1

[RobinTail]

Hello @JonathanCabezas ,

this is not a bug, it was a required breaking change to adopt Zod 4 in version 24. Here is a quote from the Changelog:

• Changes to ZodType::example() (Zod plugin method):
  • Now acts as an alias for ZodType::meta({ examples });
  • The argument has to be the output type of the schema (used to be the opposite):
    • This change is only breaking for transforming schemas;
    • In order to specify an example for an input schema the .example() method must be called before .transform();

There was also a migration advice for the case like yours:

  input: z.string()
+   .example("123")
    .transform(Number)
-   .example("123")

example("1") should be valid

It's valid depending on location.
In your code you should apply it before transformation/pipe, not after.

[JonathanCabezas]

This is a bummer. I was using some helper zod objects such as:

export const greaterThanZeroIntFromStringSchema = z
  .string()
  .transform(Number)
  .pipe(z.number().int().min(0));

Obviously I don't want the same value for my examples, which I use to generate a SwaggerUI doc automatically, for example:

const PaginationSchema = z
  .object({
    limit: greaterThanZeroIntFromStringSchema
      .optional()
      .describe("The number of items per page to return"),
    offset: greaterThanZeroIntFromStringSchema
      .optional()
      .describe("The page wanted, starting from 0"),
  })
  .example({
    limit: "2",    // <-- Not working anymore
    offset: "1" ,// <-- Not working anymore
  });

This is a feature regression as far as I'm concerned.
If you won't fix it, do you advice on how to fix it ?

[RobinTail]

If you won't fix it, do you advice on how to fix it ?

here you go, @JonathanCabezas :

const makeGreaterThanZeroIntFromStringSchemaWithExample = (example: string) => z
  .string()
  .example(example) // <—————
  .transform(Number)
  .pipe(z.number().int().min(0));

const PaginationSchema = z
  .object({
    limit: makeGreaterThanZeroIntFromStringSchemaWithExample("2")
      .optional()
      .describe("The number of items per page to return"),
    offset: makeGreaterThanZeroIntFromStringSchemaWithExample("1")
      .optional()
      .describe("The page wanted, starting from 0"),
  });

OR you can extract transformation and piping into such helper, but keep examples along with description:

const makeNonNegative = (subject: z.ZodString) =>
        subject.transform(Number).pipe(z.int().nonnegative());

makeNonNegative(z.string().describe("some").example("123"));

[JonathanCabezas]

For complicated input types it gets really verbose, and hard to read:

input: z.object({
  product_id: makeGreaterThanZeroIntFromStringSchemaWithExample("1"),
  brand: z.string().example("MyBrand"),
  price: z.number().example("3.3")
})

instead of the way more readable:

input: z.object({
  product_id: greaterThanZeroIntFromStringSchema,
  brand: z.string(),
  price: z.number()
}).example({
  product_id: "1",
  brand: "MyBrand",
  price: 3.3
})

Also I had a list of mock products I could just use in my code:

input: z.object({
  product_id: greaterThanZeroIntFromStringSchema,
  brand: z.string(),
  price: z.number()
}).example(inputExampleProducts[0])

I tried .meta(examples:[]) but I get no type safety.