v24 is for Ashley

Version 24 introduces initial support for Zod 4, requiring at least version 3.25.35, but due to the special versioning strategy of Zod all imports must be changed to zod/v4. The framework simplifies the IOSchema type to explicitly require schemas that resolve to objects. Documentation generation now uses Zod 4’s native toJSONSchema() method, with custom overrides to align with OpenAPI 3.1, and the numericRange option has been removed. The Depicter type changed its signature, and brandHandling is now implemented as a postprocessing step. The optionalPropStyle option was removed from the Integration constructor. Using the Zod's internal storage for examples: method .example() changed its argument from z.input<> to z.output<> which is breaking for transforming schemas, so that examples of its input side must be set before the transformation. The getExamples() helper removed in favour of .meta()?.examples, restored in 24.1.0.

Breaking changes

• Switched to Zod 4:
  • Minimum supported version of zod is 3.25.35, BUT imports MUST be from zod/v4;
    • Read the Explanation of the versioning strategy;
    • Express Zod API, however, is not aiming to support both Zod 3 and Zod 4 simultaneously due to:
      • incompatibility of data structures;
      • operating composite schemas (need to avoid mixing schemas of different versions);
      • the temporary nature of this transition;
      • the advantages of Zod 4 that provide opportunities to simplifications and corrections of known issues.
  • IOSchema type had to be simplified down to a schema resulting to an object, but not an array;
  • Refer to Migration guide on Zod 4 for adjusting your schemas;
• 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();
• The transforming proprietary schemas ez.dateIn() and ez.dateOut() now accept metadata as its argument:
  • This allows to set examples before transformation (ez.dateIn()) and to avoid the examples "branding";
• Changes to Documentation:
  • Generating Documentation is mostly delegated to Zod 4 z.toJSONSchema();
  • Express Zod API implements some overrides and improvements to fit it into OpenAPI 3.1 that extends JSON Schema;
  • The numericRange option removed from Documentation class constructor argument;
  • The Depicter type signature changed: became a postprocessing function returning an overridden JSON Schema;
• Changes to Integration:
  • The optionalPropStyle option removed from Integration class constructor:
  • Use .optional() to add question mark to the object property as well as undefined to its type;
  • Use .or(z.undefined()) to add undefined to the type of the object property;
  • See the reasoning;
  • Properties assigned with z.any() or z.unknown() schema are now typed as required:
    • Read the details here;
  • Added types generation for z.never(), z.void() and z.unknown() schemas;
  • The fallback type for unsupported schemas and unclear transformations in response changed from any to unknown;
• The argument of ResultHandler::handler is now discriminated: either output or error is null, not both;
• The getExamples() public helper removed — use .meta()?.examples instead, restored in 24.1.0;
• Added the new proprietary schema ez.buffer();
• The ez.file() schema removed: use z.string(), z.base64(), ez.buffer() or their union;

Migration

Consider the automated migration using the built-in ESLint rule.

// eslint.config.mjs — minimal ESLint 9 config to apply migrations automatically using "eslint --fix"
import parser from "@typescript-eslint/parser";
import migration from "express-zod-api/migration";

export default [
  { languageOptions: { parser }, plugins: { migration } },
  { files: ["**/*.ts"], rules: { "migration/v24": "error" } },
];

- import { z } from "zod";
+ import { z } from "zod/v4";

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

- ez.dateIn().example("2021-12-31");
+ ez.dateIn({ examples: ["2021-12-31"] });
- ez.file("base64");
+ z.base64();
- ez.file("buffer");
+ ez.buffer();