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

- **ID:** `llm/llm-function-call-schema-nested-ref`
- **Domain:** llm
- **Category:** config_error
- **Verification:** ai_generated
- **Fix Rate:** 85%

## Root Cause

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

## Version Compatibility

| Version | Status | Introduced | Deprecated |
|---------|--------|------------|------------|
| openai 1.15.0 | active | — | — |
| openai 1.16.0 | active | — | — |
| JSON Schema Draft 2020-12 | active | — | — |

## Workarounds

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

## Dead Ends

- **Adding more $defs entries hoping API will resolve them** — OpenAI API does not support nested $ref resolution fully; inline definitions are required. (95% fail)
- **Using JSON Schema Draft 4 instead of Draft 2020-12** — Draft 4 has different $ref handling but still not supported for nested structures in function schemas. (85% fail)