Address Zod 4.3+ Override issues (#568)

Author: samchungy

.changeset/fine-states-kiss.md

@@ -0,0 +1,5 @@
+---
+'zod-openapi': patch
+---
+
+Address Zod 4.3+ "cannot be represented in OpenAPI" compatibility issues

package.json

@@ -25,17 +25,17 @@
   "type": "module",
   "exports": {
     ".": {
-      "import": "./dist/index.js",
+      "import": "./dist/index.mjs",
       "require": "./dist/index.cjs"
     },
     "./api": {
-      "import": "./dist/api.js",
+      "import": "./dist/api.mjs",
       "require": "./dist/api.cjs"
     },
     "./package.json": "./package.json"
   },
   "main": "./dist/index.cjs",
-  "module": "./dist/index.js",
+  "module": "./dist/index.mjs",
   "types": "./dist/index.d.cts",
   "files": [
     "dist",
@@ -69,7 +69,7 @@
     "tsdown": "0.16.7",
     "vitest": "3.2.4",
     "yaml": "2.8.1",
-    "zod": "4.1.13"
+    "zod": "4.3.5"
   },
   "peerDependencies": {
     "zod": "^3.25.74 || ^4.0.0"

pnpm-lock.yaml

@@ -5,15 +5,23 @@ import { validate } from './override.js';
 
 describe('validate', () => {
   it('should throw an error for a custom optional', () => {
+    const custom = z.custom();
     expect(() =>
       validate(
         {
-          zodSchema: z.custom().optional(),
+          zodSchema: custom.optional(),
           jsonSchema: {},
           io: 'input',
           path: ['properties', 'zodOpenApiCreateSchema'],
         },
         {},
+        {
+          context: {
+            jsonSchema: {},
+            zodSchema: custom,
+            path: ['properties', 'zodOpenApiCreateSchema'],
+          },
+        },
       ),
     ).toThrowErrorMatchingInlineSnapshot(
       `[Error: Zod schema of type \`custom\` at properties > zodOpenApiCreateSchema cannot be represented in OpenAPI. Please assign it metadata with \`.meta()\`]`,
@@ -30,6 +38,7 @@ describe('validate', () => {
           path: ['properties', 'zodOpenApiCreateSchema'],
         },
         {},
+        {},
       ),
     ).toThrow(
       'Zod schema of type `void` at properties > zodOpenApiCreateSchema cannot be represented in OpenAPI. Please assign it metadata with `.meta()`',
@@ -46,6 +55,7 @@ describe('validate', () => {
           path: ['properties', 'zodOpenApiCreateSchema'],
         },
         {},
+        {},
       ),
     ).toThrow(
       'Zod schema of type `map` at properties > zodOpenApiCreateSchema cannot be represented in OpenAPI. Please assign it metadata with `.meta()`',
@@ -65,6 +75,7 @@ describe('validate', () => {
       {
         allowEmptySchema: { pipe: { output: true } },
       },
+      {},
     );
   });
 });

src/create/schema/override.test.ts

@@ -7,6 +7,8 @@ import type {
   ZodOpenApiOverrideContext,
 } from '../../types.js';
 
+import type { PreviousContext } from './schema.js';
+
 import type { oas31 } from '@zod-openapi/openapi3-ts';
 
 export const override: ZodOpenApiOverride = (ctx) => {
@@ -95,7 +97,26 @@ export const override: ZodOpenApiOverride = (ctx) => {
 export const validate = (
   ctx: ZodOpenApiOverrideContext,
   opts: CreateDocumentOptions,
+  previousContext: PreviousContext,
 ) => {
+  if (
+    previousContext.context &&
+    ctx.zodSchema._zod.parent !== previousContext.context.zodSchema
+  ) {
+    if (previousContext.context.zodSchema._zod.def.type === 'pipe') {
+      // For some reason transform calls pipe and the meta ends up on the pipe instead of the transform
+      throw new Error(
+        `Zod transform found at ${previousContext.context.path.join(' > ')} are not supported in output schemas. Please use \`.overwrite()\` or wrap the schema in a \`.pipe()\` or assign it manual metadata with \`.meta()\``,
+      );
+    }
+
+    throw new Error(
+      `Zod schema of type \`${previousContext.context.zodSchema._zod.def.type}\` at ${previousContext.context?.path.join(' > ')} cannot be represented in OpenAPI. Please assign it metadata with \`.meta()\``,
+    );
+  }
+
+  previousContext.context = undefined;
+
   if (Object.keys(ctx.jsonSchema).length) {
     return;
   }
@@ -115,6 +136,7 @@ export const validate = (
           zodSchema: def.innerType,
         } as ZodOpenApiOverrideContext,
         opts,
+        previousContext,
       );
       return;
     }
@@ -126,10 +148,14 @@ export const validate = (
     }
     case 'pipe': {
       if (ctx.io === 'output') {
-        // For some reason transform calls pipe and the meta ends up on the pipe instead of the transform
-        throw new Error(
-          `Zod transform found at ${ctx.path.join(' > ')} are not supported in output schemas. Please use \`.overwrite()\` or wrap the schema in a \`.pipe()\` or assign it manual metadata with \`.meta()\``,
-        );
+        if (!ctx.zodSchema._zod.parent) {
+          previousContext.context = ctx;
+          return;
+        }
+        // // For some reason transform calls pipe and the meta ends up on the pipe instead of the transform
+        // throw new Error(
+        //   `Zod transform found at ${ctx.path.join(' > ')} are not supported in output schemas. Please use \`.overwrite()\` or wrap the schema in a \`.pipe()\` or assign it manual metadata with \`.meta()\``,
+        // );
       }
       return;
     }
@@ -147,6 +173,12 @@ export const validate = (
       }
       return;
     }
+    case 'custom': {
+      if (!ctx.zodSchema._zod.parent) {
+        previousContext.context = ctx;
+        return;
+      }
+    }
   }
 
   throw new Error(

src/create/schema/override.ts

@@ -14,6 +14,7 @@ import type {
   ZodOpenApiComponentsObject,
 } from '../../index.js';
 import { type OpenApiVersion, satisfiesVersion } from '../../openapi.js';
+import type { OverrideParameters } from '../../zod.js';
 import { type ComponentRegistry, createRegistry } from '../components.js';
 
 import { override, validate } from './override.js';
@@ -26,6 +27,10 @@ export interface SchemaResult {
   components: Record<string, oas31.SchemaObject>;
 }
 
+export type PreviousContext = {
+  context?: OverrideParameters;
+};
+
 export const createSchema = (
   schema: core.$ZodType,
   ctx: {
@@ -129,6 +134,8 @@ export const createSchemas = <
     ? '$defs'
     : ('definitions' as '$defs');
 
+  const previousContext: PreviousContext = {};
+
   const jsonSchema = toJSONSchema(zodRegistry, {
     override(context) {
       const meta = globalRegistry.get(context.zodSchema);
@@ -158,7 +165,7 @@ export const createSchemas = <
 
       deleteInvalidJsonSchemaFields(context.jsonSchema);
       deleteZodOpenApiMeta(context.jsonSchema);
-      validate(enrichedContext, ctx.opts);
+      validate(enrichedContext, ctx.opts, previousContext);
     },
     io: ctx.io,
     unrepresentable: 'any',
@@ -175,7 +182,9 @@ export const createSchemas = <
 
   const components = jsonSchema.schemas.__shared?.[defsName] ?? {};
 
-  jsonSchema.schemas.__shared ??= { [defsName]: components };
+  jsonSchema.schemas.__shared ??= {
+    [defsName]: components,
+  } as core.ZodStandardJSONSchemaPayload<unknown>;
 
   const dynamicComponents = new Map<string, string>();
   for (const [key, value] of Object.entries(components)) {
@@ -218,7 +227,9 @@ export const createSchemas = <
   ) as typeof jsonSchema;
 
   const parsedComponents = parsedJsonSchema.schemas.__shared?.[defsName] ?? {};
-  parsedJsonSchema.schemas.__shared ??= { [defsName]: parsedComponents };
+  parsedJsonSchema.schemas.__shared ??= {
+    [defsName]: parsedComponents,
+  } as core.ZodStandardJSONSchemaPayload<unknown>;
 
   for (const [key] of ctx.registry.components.schemas.manual) {
     const manualComponent = parsedJsonSchema.schemas[key];

src/create/schema/schema.ts

@@ -200,7 +200,6 @@ describe('string', () => {
     ${z.email()}        | ${'email'}
     ${z.iso.datetime()} | ${'date-time'}
     ${z.iso.date()}     | ${'date'}
-    ${z.iso.time()}     | ${'time'}
     ${z.iso.duration()} | ${'duration'}
     ${z.ipv4()}         | ${'ipv4'}
     ${z.ipv6()}         | ${'ipv6'}

src/create/schema/tests/string.test.ts

@@ -1,13 +1,9 @@
 /* eslint-disable @typescript-eslint/no-empty-object-type */
-import type { JSONSchemaMeta, toJSONSchema } from 'zod/v4/core';
+import type { JSONSchemaMeta } from 'zod/v4/core';
 
-import type { oas31 } from '@zod-openapi/openapi3-ts';
-
-type OverrideParameters = Parameters<
-  NonNullable<NonNullable<Parameters<typeof toJSONSchema>[1]>['override']>
->[0];
+import type { OverrideParameters, OverrideSchemaParameters } from './zod.js';
 
-type OverrideSchemaParameters = Omit<OverrideParameters, 'zodSchema'>;
+import type { oas31 } from '@zod-openapi/openapi3-ts';
 
 export type ZodOpenApiOverrideContext = OverrideParameters & {
   io: 'input' | 'output';

src/types.ts

@@ -1,4 +1,11 @@
 import type * as core from 'zod/v4/core';
+import type { toJSONSchema } from 'zod/v4/core';
 
 export const isAnyZodType = (schema: unknown): schema is core.$ZodTypes =>
   typeof schema === 'object' && schema !== null && '_zod' in schema;
+
+export type OverrideParameters = Parameters<
+  NonNullable<NonNullable<Parameters<typeof toJSONSchema>[1]>['override']>
+>[0];
+
+export type OverrideSchemaParameters = Omit<OverrideParameters, 'zodSchema'>;

src/zod.ts

@@ -1,8 +1,9 @@
+// @ts-check
 import { defineConfig } from 'tsdown/config';
 
 export default defineConfig({
   entry: ['src/index.ts', 'src/api.ts'],
-  format: ['esm', 'cjs'],
+  format: ['cjs', 'esm'],
   exports: true,
   dts: {
     resolve: ['@zod-openapi/openapi3-ts'],