JSONSchema does not support recursive refs & zod also fails to convert similar schemas to JSONSchema correctly
Problem
Confirm this is a Node library issue and not an underlying OpenAI API issue - [X] This is an issue with the Node library Describe the bug Copy and pasting example schemas (zod included) from the latest documents results in errors when using the latest openai sdk and having a focus on $ref for the new response_format that supports JSONSchema. zods example @ https://platform.openai.com/docs/guides/structured-outputs/ui-generation [code block] and any JSONSchema example I've tried (e.g. https://platform.openai.com/docs/guides/structured-outputs/recursive-schemas-are-supported) [code block] Initial debugging suggests that the Zod to JSONSchema conversion code looks for `definitions` and `$defs` is not considered.. but then when the resulting schema is used, it requires `$defs` 🤷 so the generated schema from zod is invalid). For the JSONSchema, it struggles with a lot but when I get it to pass the simple syntax validation, it falls over on the server and I cannot figure out where the issue lies based on the error. To Reproduce 1. Install latest "openai": "^4.55.0" 2. copy any of the zod or schemas that include definitions, $defs, or recursive schemas. 3. invoke the API via any of the usual ways with the new `response_format` [code block] (helps to also include `DEBUG=true` when running though nothing valuable appears to be thrown) Code snippets _No response_ OS macOS Node version bun 1.1.20 Library version 4.55.0
Error Output
Error } from "./core.mjs";
Unverified for your environment
Select your OS to check compatibility.
1 Fix
Fix Recursive Ref Handling in Zod to JSONSchema Conversion
The Zod library's conversion to JSONSchema does not correctly handle `$defs` for recursive schemas, leading to invalid schemas being generated. The OpenAI API expects schemas to use `$defs` for definitions, but the generated schemas from Zod may not include this, causing errors during API invocation.
Awaiting Verification
Be the first to verify this fix
- 1
Update Zod Library
Ensure you are using the latest version of the Zod library, as updates may include fixes for JSONSchema conversion issues.
bashnpm install zod@latest - 2
Modify Zod Schema Definitions
Update your Zod schemas to explicitly use `$defs` for any definitions. This ensures compatibility with the OpenAI API's expected schema format.
typescriptconst schema = z.object({ name: z.string(), children: z.array(z.ref('$defs.child')) }).$defs = { child: z.object({ name: z.string(), children: z.array(z.ref('$defs.child')) }) }; - 3
Validate JSONSchema Output
After modifying the schemas, validate the generated JSONSchema output against a JSONSchema validator to ensure it meets the required standards.
javascriptconst Ajv = require('ajv'); const ajv = new Ajv(); const valid = ajv.validate(schema, jsonSchemaOutput); if (!valid) console.log(ajv.errors); - 4
Test API Invocation
Invoke the OpenAI API with the updated schema and check for errors. Ensure to set `DEBUG=true` to capture any additional logs that may help in debugging.
javascriptconst response = await openai.apiCall({ model: 'gpt-3.5-turbo', messages: [{ role: 'user', content: '...' }], response_format: 'jsonschema', schema: jsonSchemaOutput }); - 5
Review API Response
Check the API response for correctness and ensure that the schema is being processed without errors. If errors persist, review the schema structure and validate against the OpenAI documentation.
javascript// Check response console.log(response);
Validation
Confirm the fix worked by successfully invoking the OpenAI API without errors related to schema validation. Additionally, ensure that the schema adheres to the expected structure by reviewing the API response.
Sign in to verify this fix
Environment
Submitted by
Alex Chen
2450 rep