llm config_error ai_generated true

InvalidRequestError: Function schema '$defs/Location' not found in definitions. Nested $ref not resolved.

ID: llm/llm-function-call-schema-nested-ref

Also available as: JSON · Markdown · 中文
85%Fix Rate
87%Confidence
1Evidence
2024-06-15First Seen

Version Compatibility

VersionStatusIntroducedDeprecatedNotes
openai 1.15.0 active — — —
openai 1.16.0 active — — —
JSON Schema Draft 2020-12 active — — —

Root Cause

OpenAI function calling schema with nested JSON Schema $ref references that are not properly resolved by the API, causing schema validation failure.

generic

中文

OpenAI函数调用模式中包含嵌套的JSON Schema $ref引用，API未能正确解析，导致模式验证失败。

Official Documentation

https://platform.openai.com/docs/guides/function-calling

Workarounds

  1. 95% success Flatten all nested schemas by inlining definitions: replace '$ref': '#/$defs/Location' with the actual Location schema object directly in the function parameters 
    Flatten all nested schemas by inlining definitions: replace '$ref': '#/$defs/Location' with the actual Location schema object directly in the function parameters
  2. 90% success Use a schema bundler like 'json-schema-ref-parser' to dereference before sending: const dereferenced = await $RefParser.dereference(schema); 
    Use a schema bundler like 'json-schema-ref-parser' to dereference before sending: const dereferenced = await $RefParser.dereference(schema);

中文步骤

  1. Flatten all nested schemas by inlining definitions: replace '$ref': '#/$defs/Location' with the actual Location schema object directly in the function parameters
  2. Use a schema bundler like 'json-schema-ref-parser' to dereference before sending: const dereferenced = await $RefParser.dereference(schema);

Dead Ends

Common approaches that don't work:

  1. Adding more $defs entries hoping API will resolve them 95% fail

    OpenAI API does not support nested $ref resolution fully; inline definitions are required.

  2. Using JSON Schema Draft 4 instead of Draft 2020-12 85% fail

    Draft 4 has different $ref handling but still not supported for nested structures in function schemas.