Confirm this is a Node library issue and not an underlying OpenAI API issue
Describe the bug
When using zodTextFormat to convert a Zod schema, the generated JSON schema contains a $ref that references itself, creating an invalid circular definition that cannot be resolved.
To Reproduce
- Create a Zod schema as shown in the code snippet.
- Pass it to zodTextFormat(schema, "slidePlan").
- Inspect the generated definitions block in the output.
Notes:
- Only occurs for
zod/v3
- Seems to be related to the
brand applied to BlockIdSchema
- If the result is used for
text.format of a responses.parse() call, a rather cryptic error is shown:
SyntaxError: Unexpected end of JSON input
at JSON.parse (<anonymous>)
Code snippets
import { zodTextFormat } from "openai/helpers/zod";
import { z } from "zod/v3";
const BlockIdSchema = z.string().brand<"SlideId">();
const SlidePlanSchema = z.object({
slides: z.array(
z.object({
subtitle: z.array(BlockIdSchema).nullable(),
content: z.array(BlockIdSchema).min(1),
}),
),
});
const jsonSchema = zodTextFormat(SlidePlanSchema, "slidePlan");
console.dir(jsonSchema, { depth: null });This outputs:
{
type: 'json_schema',
name: 'slidePlan',
strict: true,
schema: {
type: 'object',
properties: {
slides: {
type: 'array',
items: {
type: 'object',
properties: {
subtitle: {
anyOf: [
{ type: 'array', items: { type: 'string' } },
{ type: 'null' }
]
},
content: {
type: 'array',
items: {
'$ref': '#/definitions/slidePlan_properties_slides_items_properties_subtitle_anyOf_0_items'
},
minItems: 1
}
},
required: [ 'subtitle', 'content' ],
additionalProperties: false
}
}
},
required: [ 'slides' ],
additionalProperties: false,
definitions: {
slidePlan_properties_slides_items_properties_subtitle_anyOf_0_items: {
'$ref': '#/definitions/slidePlan_properties_slides_items_properties_subtitle_anyOf_0_items'
},
slidePlan: {
type: 'object',
properties: {
slides: {
type: 'array',
items: {
type: 'object',
properties: {
subtitle: {
anyOf: [
{ type: 'array', items: { type: 'string' } },
{ type: 'null' }
]
},
content: {
type: 'array',
items: {
'$ref': '#/definitions/slidePlan_properties_slides_items_properties_subtitle_anyOf_0_items'
},
minItems: 1
}
},
required: [ 'subtitle', 'content' ],
additionalProperties: false
}
}
},
required: [ 'slides' ],
additionalProperties: false
}
},
'$schema': 'http://json-schema.org/draft-07/schema#'
}
}Under definitions, there is a circular reference:
definitions: {
slidePlan_properties_slides_items_properties_subtitle_anyOf_0_items: {
'$ref': '#/definitions/slidePlan_properties_slides_items_properties_subtitle_anyOf_0_items'
},
...OS
Ubuntu
Node version
v24.13.0
Library version
openai v6.17.0
Confirm this is a Node library issue and not an underlying OpenAI API issue
Describe the bug
When using
zodTextFormatto convert a Zod schema, the generated JSON schema contains a$refthat references itself, creating an invalid circular definition that cannot be resolved.To Reproduce
Notes:
zod/v3brandapplied toBlockIdSchematext.formatof aresponses.parse()call, a rather cryptic error is shown:Code snippets
This outputs:
{ type: 'json_schema', name: 'slidePlan', strict: true, schema: { type: 'object', properties: { slides: { type: 'array', items: { type: 'object', properties: { subtitle: { anyOf: [ { type: 'array', items: { type: 'string' } }, { type: 'null' } ] }, content: { type: 'array', items: { '$ref': '#/definitions/slidePlan_properties_slides_items_properties_subtitle_anyOf_0_items' }, minItems: 1 } }, required: [ 'subtitle', 'content' ], additionalProperties: false } } }, required: [ 'slides' ], additionalProperties: false, definitions: { slidePlan_properties_slides_items_properties_subtitle_anyOf_0_items: { '$ref': '#/definitions/slidePlan_properties_slides_items_properties_subtitle_anyOf_0_items' }, slidePlan: { type: 'object', properties: { slides: { type: 'array', items: { type: 'object', properties: { subtitle: { anyOf: [ { type: 'array', items: { type: 'string' } }, { type: 'null' } ] }, content: { type: 'array', items: { '$ref': '#/definitions/slidePlan_properties_slides_items_properties_subtitle_anyOf_0_items' }, minItems: 1 } }, required: [ 'subtitle', 'content' ], additionalProperties: false } } }, required: [ 'slides' ], additionalProperties: false } }, '$schema': 'http://json-schema.org/draft-07/schema#' } }Under definitions, there is a circular reference:
OS
Ubuntu
Node version
v24.13.0
Library version
openai v6.17.0