Support for zod 4

[kenn]

Confirm this is a Node library issue and not an underlying OpenAI API issue

• This is an issue with the Node library

Describe the bug

Hey OpenAI team 👋

After updating to Zod v4 I’m hitting this runtime error:

✘ [ERROR] No matching export in "node_modules/.pnpm/zod@4.0.2/node_modules/zod/index.js" for import "ZodFirstPartyTypeKind"

    node_modules/.pnpm/openai@5.8.3_ws@8.18.3_zod@4.0.2/node_modules/openai/_vendor/zod-to-json-schema/parsers/array.mjs:1:9:
      1 │ import { ZodFirstPartyTypeKind } from 'zod';
        ╵          ~~~~~~~~~~~~~~~~~~~~~

Looks like the vendored zod-to-json-schema in openai/helpers/zod still expects the ZodFirstPartyTypeKind export, which was removed in Zod v4.

Notes / ideas

• Pinning zod@3 is a temporary workaround, but it blocks upgrading the whole stack.
• A quick fix might be bumping the vendored zod-to-json-schema to a version that supports Zod v4 or swapping it out for the maintained @asteasolutions/zod-to-openapi which already handles the new internals.

Thanks for taking a look! Let me know if I can help with more info or a PR.

To Reproduce

1. Fresh project with pnpm
2. pnpm add openai@5.8.3 zod@^4
3. Add a simple script: import { zodResponseFormat } from 'openai/helpers/zod'
4. pnpm tsx index.ts (or just bundle with esbuild) → error above.

Code snippets

OS

macOS

Node version

Node v22

Library version

Latest

[mjakl]

I also stumbled upon this, esp. because the compiler does not detect the problem (it's a runtime issue).

According to this comment the zod helpers are not needed anymore (zod offers JSON Schema output nateively now). This works fine, but loses type inference. I came up with a small helper based on parts of the original zod helpers that preserves type information:

function jsonSchema(
  name: string,
  schema: z.ZodType,
): AutoParseableTextFormat<z.infer<typeof schema>> {
  return {
    name,
    schema: z.toJSONSchema(schema, { target: "draft-7" }),
    type: "json_schema",
    strict: true,
    $brand: "auto-parseable-response-format",
    $parseRaw: (x) => schema.parse(x),
  } as AutoParseableTextFormat<z.infer<typeof schema>>;
}

Usage:

const response = await client.responses.parse({
  model: env.MODEL,
  input: "Who is or was the greatest scientist of all time?",
  text: {
    format: jsonSchema("router", OutputRouter),
  },
});

response.output_parsed is now of type z.infer<typeof OutputRouter> | null.

HTH

[wojtekmaj]

Here are drop-in replacements for existing failing utils.

import { z } from 'zod';
import { makeParseableResponseFormat, makeParseableTextFormat } from 'openai/lib/parser';

import type { AutoParseableResponseFormat, AutoParseableTextFormat } from 'openai/lib/parser';
import type { ResponseFormatJSONSchema } from 'openai/resources';
import type { ResponseFormatTextJSONSchemaConfig } from 'openai/resources/responses/responses';

export function zodResponseFormat<ZodInput extends z.ZodType>(
  zodObject: ZodInput,
  name: string,
  props?: Omit<ResponseFormatJSONSchema.JSONSchema, 'schema' | 'strict' | 'name'>,
): AutoParseableResponseFormat<z.infer<ZodInput>> {
  return makeParseableResponseFormat(
    {
      type: 'json_schema',
      json_schema: {
        ...props,
        name,
        strict: true,
        schema: z.toJSONSchema(zodObject, { target: 'draft-7' }),
      },
    },
    (content) => zodObject.parse(JSON.parse(content)),
  );
}

export function zodTextFormat<ZodInput extends z.ZodType>(
  zodObject: ZodInput,
  name: string,
  props?: Omit<ResponseFormatTextJSONSchemaConfig, 'schema' | 'type' | 'strict' | 'name'>,
): AutoParseableTextFormat<z.infer<ZodInput>> {
  return makeParseableTextFormat(
    {
      type: 'json_schema',
      ...props,
      name,
      strict: true,
      schema: z.toJSONSchema(zodObject, { target: 'draft-7' }),
    },
    (content) => zodObject.parse(JSON.parse(content)),
  );
}

Usage: Just like the originals :)

[Xhale1]

Out of curiosity, what's the reason for using the older draft-7 instead of draft-2020-12?

[colinhacks]

Found a workaround for this on Zod's end. Upgrade to zod@^4.0.4 and this error should go away.

Regarding Zod 4 support generally, the workarond is to convert your schemas to JSON Schema yourself with z.toJSONSchema(): #1540 (comment)

But also, yeah, they should add Zod 4 support to zodResponseFormat whenever possible: https://zod.dev/library-authors

[provsalt]

just got this problem as well. I agree that they should add the zod 4 support to the zodResponseFormat for forward compatibility. If not the documentation should reflect the workaround.

[wojtekmaj]

Out of curiosity, what's the reason for using the older draft-7 instead of draft-2020-12?

@Xhale1 Because that's what the OpenAI-provided helpers seem to output as well.

Found a workaround for this on Zod's end. Upgrade to zod@^4.0.4 and this error should go away.

@colinhacks Something is still not clicking, but it seems to be an issue on OpenAI's side.

zodTextFormat(z.object({ response: z.string() }), 'response'),
zodTextFormat(z.string(), 'response'));

BOTH produce:

{
  type: 'json_schema',
  name: 'response',
  strict: true,
  schema: {
    type: 'string',
    '$schema': 'http://json-schema.org/draft-07/schema#'
  }
}

While my "drop-in replacement" (#1576 (comment)) produces

{
  type: 'json_schema',
  name: 'response',
  strict: true,
  schema: {
    '$schema': 'http://json-schema.org/draft-07/schema#',
    type: 'object',
    properties: { response: [Object] },
    required: [ 'response' ],
    additionalProperties: false
  }
}

for the first example. Using the original, OpenAI-provided function will lead to Error 400.