{
  "id": "llm/llm-function-call-schema-nested-ref",
  "signature": "InvalidRequestError: Function schema '$defs/Location' not found in definitions. Nested $ref not resolved.",
  "signature_zh": "无效请求错误：函数模式中未找到'$defs/Location'定义。嵌套的$ref未解析。",
  "regex": "Function schema.*not found.*definitions",
  "domain": "llm",
  "category": "config_error",
  "subcategory": null,
  "root_cause": "OpenAI function calling schema with nested JSON Schema $ref references that are not properly resolved by the API, causing schema validation failure.",
  "root_cause_type": "generic",
  "root_cause_zh": "OpenAI函数调用模式中包含嵌套的JSON Schema $ref引用，API未能正确解析，导致模式验证失败。",
  "versions": [
    {
      "version": "openai 1.15.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "openai 1.16.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "JSON Schema Draft 2020-12",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    }
  ],
  "os_specific": {},
  "dead_ends": [
    {
      "action": "Adding more $defs entries hoping API will resolve them",
      "why_fails": "OpenAI API does not support nested $ref resolution fully; inline definitions are required.",
      "fail_rate": 0.95,
      "condition": "",
      "sources": []
    },
    {
      "action": "Using JSON Schema Draft 4 instead of Draft 2020-12",
      "why_fails": "Draft 4 has different $ref handling but still not supported for nested structures in function schemas.",
      "fail_rate": 0.85,
      "condition": "",
      "sources": []
    }
  ],
  "workarounds": [
    {
      "action": "Flatten all nested schemas by inlining definitions: replace '$ref': '#/$defs/Location' with the actual Location schema object directly in the function parameters",
      "success_rate": 0.95,
      "how": "Flatten all nested schemas by inlining definitions: replace '$ref': '#/$defs/Location' with the actual Location schema object directly in the function parameters",
      "condition": "",
      "sources": []
    },
    {
      "action": "Use a schema bundler like 'json-schema-ref-parser' to dereference before sending: const dereferenced = await $RefParser.dereference(schema);",
      "success_rate": 0.9,
      "how": "Use a schema bundler like 'json-schema-ref-parser' to dereference before sending: const dereferenced = await $RefParser.dereference(schema);",
      "condition": "",
      "sources": []
    }
  ],
  "workarounds_zh": [
    "Flatten all nested schemas by inlining definitions: replace '$ref': '#/$defs/Location' with the actual Location schema object directly in the function parameters",
    "Use a schema bundler like 'json-schema-ref-parser' to dereference before sending: const dereferenced = await $RefParser.dereference(schema);"
  ],
  "transition_graph": {
    "leads_to": [],
    "preceded_by": [],
    "frequently_confused_with": []
  },
  "official_doc_url": "https://platform.openai.com/docs/guides/function-calling",
  "official_doc_section": null,
  "error_code": null,
  "verification_tier": "ai_generated",
  "confidence": 0.87,
  "fix_success_rate": 0.85,
  "resolvable": "true",
  "first_seen": "2024-06-15",
  "last_confirmed": "2024-06-01",
  "last_updated": "2024-06-01",
  "evidence_count": 1,
  "tags": [],
  "locale": "en",
  "aliases": []
}