feat: add support for zod@4 schemas (#1666)

karpetrosyan · RobertCraigie · web-flow · commit 10ef7ff4cb4a · 2025-10-24T12:46:33.000+01:00
Co-authored-by: Robert Craigie &lt;robert@craigie.dev&gt;
diff --git a/examples/parsing-run-tools.ts b/examples/parsing-run-tools.ts
@@ -1,5 +1,5 @@
 import OpenAI from 'openai';
-import z from 'zod/v3';
+import z from 'zod/v4'; // Also works for 'zod/v3'
 import { zodFunction } from 'openai/helpers/zod';
 
 const Table = z.enum(['orders', 'customers', 'products']);
diff --git a/examples/parsing-stream.ts b/examples/parsing-stream.ts
@@ -1,6 +1,6 @@
 import { zodResponseFormat } from 'openai/helpers/zod';
 import OpenAI from 'openai/index';
-import { z } from 'zod/v3';
+import { z } from 'zod/v4'; // Also works for 'zod/v3'
 
 const Step = z.object({
   explanation: z.string(),
diff --git a/examples/parsing-tools-stream.ts b/examples/parsing-tools-stream.ts
@@ -1,6 +1,6 @@
 import { zodFunction } from 'openai/helpers/zod';
 import OpenAI from 'openai/index';
-import { z } from 'zod/v3';
+import { z } from 'zod/v4'; // Also works for 'zod/v3'
 
 const GetWeatherArgs = z.object({
   city: z.string(),
diff --git a/examples/parsing-tools.ts b/examples/parsing-tools.ts
@@ -1,6 +1,6 @@
 import { zodFunction } from 'openai/helpers/zod';
 import OpenAI from 'openai/index';
-import { z } from 'zod/v3';
+import { z } from 'zod/v4'; // Also works for 'zod/v3'
 
 const Table = z.enum(['orders', 'customers', 'products']);
 
diff --git a/examples/parsing.ts b/examples/parsing.ts
@@ -1,6 +1,6 @@
 import { zodResponseFormat } from 'openai/helpers/zod';
 import OpenAI from 'openai/index';
-import { z } from 'zod/v3';
+import { z } from 'zod/v4'; // Also works for 'zod/v3'
 
 const Step = z.object({
   explanation: z.string(),
diff --git a/examples/responses/streaming-tools.ts b/examples/responses/streaming-tools.ts
@@ -2,7 +2,7 @@
 
 import { OpenAI } from 'openai';
 import { zodResponsesFunction } from 'openai/helpers/zod';
-import { z } from 'zod/v3';
+import { z } from 'zod/v4'; // Also works for 'zod/v3'
 
 const Table = z.enum(['orders', 'customers', 'products']);
 const Column = z.enum([
diff --git a/examples/responses/structured-outputs-tools.ts b/examples/responses/structured-outputs-tools.ts
@@ -2,7 +2,7 @@
 
 import { OpenAI } from 'openai';
 import { zodResponsesFunction } from 'openai/helpers/zod';
-import { z } from 'zod/v3';
+import { z } from 'zod/v4'; // Also works for 'zod/v3'
 
 const Table = z.enum(['orders', 'customers', 'products']);
 const Column = z.enum([
diff --git a/examples/responses/structured-outputs.ts b/examples/responses/structured-outputs.ts
@@ -2,7 +2,7 @@
 
 import { OpenAI } from 'openai';
 import { zodTextFormat } from 'openai/helpers/zod';
-import { z } from 'zod/v3';
+import { z } from 'zod/v4'; // Also works for 'zod/v3'
 
 const Step = z.object({
   explanation: z.string(),
diff --git a/examples/tool-call-helpers-zod.ts b/examples/tool-call-helpers-zod.ts
@@ -2,7 +2,7 @@
 
 import OpenAI from 'openai';
 import { zodFunction } from 'openai/helpers/zod';
-import { z } from 'zod/v3';
+import { z } from 'zod/v4'; // Also works for 'zod/v3'
 
 // gets API Key from environment variable OPENAI_API_KEY
 const openai = new OpenAI();
diff --git a/examples/ui-generation.ts b/examples/ui-generation.ts
@@ -1,5 +1,5 @@
 import OpenAI from 'openai';
-import { z } from 'zod/v3';
+import { z } from 'zod/v4'; // Also works for 'zod/v3'
 import { zodResponseFormat } from 'openai/helpers/zod';
 
 const openai = new OpenAI();
diff --git a/package.json b/package.json
@@ -36,6 +36,7 @@
     "@types/node": "^20.17.6",
     "@typescript-eslint/eslint-plugin": "8.31.1",
     "@typescript-eslint/parser": "8.31.1",
+    "deep-object-diff": "^1.1.9",
     "eslint": "^9.20.1",
     "eslint-plugin-prettier": "^5.4.1",
     "eslint-plugin-unused-imports": "^4.1.4",
diff --git a/src/helpers/zod.ts b/src/helpers/zod.ts
@@ -1,5 +1,6 @@
 import { ResponseFormatJSONSchema } from '../resources/index';
-import type { infer as zodInfer, ZodType } from 'zod/v3';
+import { z as z3 } from 'zod/v3';
+import { z as z4 } from 'zod/v4';
 import {
   AutoParseableResponseFormat,
   AutoParseableTextFormat,
@@ -11,8 +12,15 @@ import {
 import { zodToJsonSchema as _zodToJsonSchema } from '../_vendor/zod-to-json-schema';
 import { AutoParseableResponseTool, makeParseableResponseTool } from '../lib/ResponsesParser';
 import { type ResponseFormatTextJSONSchemaConfig } from '../resources/responses/responses';
+import { toStrictJsonSchema } from '../lib/transform';
+import { JSONSchema } from '../lib/jsonschema';
 
-function zodToJsonSchema(schema: ZodType, options: { name: string }): Record<string, unknown> {
+type InferZodType<T> =
+  T extends z4.ZodType ? z4.infer<T>
+  : T extends z3.ZodType ? z3.infer<T>
+  : never;
+
+function zodV3ToJsonSchema(schema: z3.ZodType, options: { name: string }): Record<string, unknown> {
   return _zodToJsonSchema(schema, {
     openaiStrictMode: true,
     name: options.name,
@@ -22,6 +30,18 @@ function zodToJsonSchema(schema: ZodType, options: { name: string }): Record<str
   });
 }
 
+function zodV4ToJsonSchema(schema: z4.ZodType): Record<string, unknown> {
+  return toStrictJsonSchema(
+    z4.toJSONSchema(schema, {
+      target: 'draft-7',
+    }) as JSONSchema,
+  ) as Record<string, unknown>;
+}
+
+function isZodV4(zodObject: z3.ZodType | z4.ZodType): zodObject is z4.ZodType {
+  return '_zod' in zodObject;
+}
+
 /**
  * Creates a chat completion `JSONSchema` response format object from
  * the given Zod schema.
@@ -59,37 +79,37 @@ function zodToJsonSchema(schema: ZodType, options: { name: string }): Record<str
  * This can be passed directly to the `.create()` method but will not
  * result in any automatic parsing, you'll have to parse the response yourself.
  */
-export function zodResponseFormat<ZodInput extends ZodType>(
+export function zodResponseFormat<ZodInput extends z3.ZodType | z4.ZodType>(
   zodObject: ZodInput,
   name: string,
   props?: Omit<ResponseFormatJSONSchema.JSONSchema, 'schema' | 'strict' | 'name'>,
-): AutoParseableResponseFormat<zodInfer<ZodInput>> {
+): AutoParseableResponseFormat<InferZodType<ZodInput>> {
   return makeParseableResponseFormat(
     {
       type: 'json_schema',
       json_schema: {
         ...props,
         name,
         strict: true,
-        schema: zodToJsonSchema(zodObject, { name }),
+        schema: isZodV4(zodObject) ? zodV4ToJsonSchema(zodObject) : zodV3ToJsonSchema(zodObject, { name }),
       },
     },
     (content) => zodObject.parse(JSON.parse(content)),
   );
 }
 
-export function zodTextFormat<ZodInput extends ZodType>(
+export function zodTextFormat<ZodInput extends z3.ZodType | z4.ZodType>(
   zodObject: ZodInput,
   name: string,
   props?: Omit<ResponseFormatTextJSONSchemaConfig, 'schema' | 'type' | 'strict' | 'name'>,
-): AutoParseableTextFormat<zodInfer<ZodInput>> {
+): AutoParseableTextFormat<InferZodType<ZodInput>> {
   return makeParseableTextFormat(
     {
       type: 'json_schema',
       ...props,
       name,
       strict: true,
-      schema: zodToJsonSchema(zodObject, { name }),
+      schema: isZodV4(zodObject) ? zodV4ToJsonSchema(zodObject) : zodV3ToJsonSchema(zodObject, { name }),
     },
     (content) => zodObject.parse(JSON.parse(content)),
   );
@@ -100,23 +120,26 @@ export function zodTextFormat<ZodInput extends ZodType>(
  * automatically by the chat completion `.runTools()` method or automatically
  * parsed by `.parse()` / `.stream()`.
  */
-export function zodFunction<Parameters extends ZodType>(options: {
+export function zodFunction<Parameters extends z3.ZodType | z4.ZodType>(options: {
   name: string;
   parameters: Parameters;
-  function?: ((args: zodInfer<Parameters>) => unknown | Promise<unknown>) | undefined;
+  function?: ((args: InferZodType<Parameters>) => unknown | Promise<unknown>) | undefined;
   description?: string | undefined;
 }): AutoParseableTool<{
   arguments: Parameters;
   name: string;
-  function: (args: zodInfer<Parameters>) => unknown;
+  function: (args: InferZodType<Parameters>) => unknown;
 }> {
   // @ts-expect-error TODO
   return makeParseableTool<any>(
     {
       type: 'function',
       function: {
         name: options.name,
-        parameters: zodToJsonSchema(options.parameters, { name: options.name }),
+        parameters:
+          isZodV4(options.parameters) ?
+            zodV4ToJsonSchema(options.parameters)
+          : zodV3ToJsonSchema(options.parameters, { name: options.name }),
         strict: true,
         ...(options.description ? { description: options.description } : undefined),
       },
@@ -128,21 +151,24 @@ export function zodFunction<Parameters extends ZodType>(options: {
   );
 }
 
-export function zodResponsesFunction<Parameters extends ZodType>(options: {
+export function zodResponsesFunction<Parameters extends z3.ZodType | z4.ZodType>(options: {
   name: string;
   parameters: Parameters;
-  function?: ((args: zodInfer<Parameters>) => unknown | Promise<unknown>) | undefined;
+  function?: ((args: InferZodType<Parameters>) => unknown | Promise<unknown>) | undefined;
   description?: string | undefined;
 }): AutoParseableResponseTool<{
   arguments: Parameters;
   name: string;
-  function: (args: zodInfer<Parameters>) => unknown;
+  function: (args: InferZodType<Parameters>) => unknown;
 }> {
   return makeParseableResponseTool<any>(
     {
       type: 'function',
       name: options.name,
-      parameters: zodToJsonSchema(options.parameters, { name: options.name }),
+      parameters:
+        isZodV4(options.parameters) ?
+          zodV4ToJsonSchema(options.parameters)
+        : zodV3ToJsonSchema(options.parameters, { name: options.name }),
       strict: true,
       ...(options.description ? { description: options.description } : undefined),
     },
diff --git a/src/lib/jsonschema.ts b/src/lib/jsonschema.ts
@@ -131,6 +131,30 @@ export interface JSONSchema {
   oneOf?: JSONSchemaDefinition[] | undefined;
   not?: JSONSchemaDefinition | undefined;
 
+  /**
+   * @see https://json-schema.org/draft/2020-12/json-schema-core.html#section-8.2.4
+   */
+  $defs?:
+    | {
+        [key: string]: JSONSchemaDefinition;
+      }
+    | undefined;
+
+  /**
+   * @deprecated Use $defs instead (draft 2019-09+)
+   * @see https://tools.ietf.org/doc/html/draft-handrews-json-schema-validation-01#page-22
+   */
+  definitions?:
+    | {
+        [key: string]: JSONSchemaDefinition;
+      }
+    | undefined;
+
+  /**
+   * @see https://json-schema.org/draft/2020-12/json-schema-core#ref
+   */
+  $ref?: string | undefined;
+
   /**
    * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-7
    */
diff --git a/src/lib/transform.ts b/src/lib/transform.ts
diff --git a/tests/helpers/zod.test.ts b/tests/helpers/zod.test.ts
diff --git a/tests/lib/ChatCompletionStream.test.ts b/tests/lib/ChatCompletionStream.test.ts
diff --git a/tests/lib/parser.test.ts b/tests/lib/parser.test.ts
diff --git a/tests/lib/transform.test.ts b/tests/lib/transform.test.ts
diff --git a/yarn.lock b/yarn.lock
