FG
💻 Software🤖 AI & LLMsOpenAI

Zod => JSONSchema conversion creates references to unknown definitions

Fresh3 days ago
Mar 14, 20260 views
Confidence Score49%
49%

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 When compiling a zod schema with multiple references to the same nullable object, the compiled JSONSchema refers to definitions that don't exist. This is using the latest version of the openai client with structured output support. I believe the issue comes from an extracted definition trying to reference an inner extracted definition again -- see the example below. To Reproduce Here's an example zod schema and function call which triggers the issue: [code block] When run, I get this error: [code block] I ninja'd into the source and console.log'd the generated JSON schema, here's what comes out: [code block] Code snippets _No response_ OS macOS Node version v22.2.0 Library version 4.55.3

Unverified for your environment

Select your OS to check compatibility.

1 Fix

Canonical Fix
Unverified Fix
New Fix – Awaiting Verification

Fix Zod to JSONSchema Conversion for Nullable Object References

Medium Risk

The issue arises because the Zod schema is generating multiple references to the same nullable object, but the JSONSchema output does not correctly define these references. This leads to undefined references in the generated JSONSchema, causing errors when the schema is validated or used.

Awaiting Verification

Be the first to verify this fix

  1. 1

    Update Zod Schema Definitions

    Ensure that all nullable objects are defined once at the root level of the JSONSchema to avoid duplicate references. This can be done by restructuring the Zod schema to use a single definition for the nullable object.

    typescript
    const NullableObject = z.object({ /* your object schema */ }).nullable();
const MainSchema = z.object({
  field1: NullableObject,
  field2: NullableObject
});
  2. 2

    Modify JSONSchema Generation Logic

    If you have access to the JSONSchema generation logic, modify it to ensure that it correctly handles references to the same definitions. This may involve checking if a definition has already been created before adding a new reference.

    typescript
    // Pseudocode for checking existing definitions
if (!definitions.includes(nullableObjectDefinition)) {
  definitions.push(nullableObjectDefinition);
}
  3. 3

    Test the Updated Schema

    Run tests to validate that the updated Zod schema compiles correctly into JSONSchema without undefined references. Use a testing framework to automate this process.

    typescript
    import { z } from 'zod';

const result = MainSchema.safeParse(data);
console.log(result.success); // Should be true if valid
  4. 4

    Review and Update Dependencies

    Check for any updates to the Zod library or related dependencies that may address this issue. Update to the latest stable versions if available.

    bash
    npm update zod

Validation

Confirm that the generated JSONSchema no longer includes references to undefined definitions by inspecting the output after applying the fixes. Run validation tests against the updated schema to ensure it behaves as expected.

Sign in to verify this fix

Environment

Submitted by

AC

Alex Chen

2450 rep

Tags

openaigptllmapibug