Fails to resolve local relative $ref references to external files on macOS (zsh) and official Kiota Docker container
- Dominant language
- C#
- Stars
- 3.8k
- Forks
- 333
- Avg merge
- 16h 29m
- Merged PRs (30d)
- 116
Description
### What are you generating using Kiota, clients or plugins?
API Client/SDK
### In what context or format are you using Kiota?
Mac executable
### Client library/SDK language
None
### Describe the bug
Kiota fails to resolve local relative `$ref` references to external files on macOS (zsh) and also in the official Kiota Docker container.
Given an OpenAPI file (`petstore_minimal.json`) that references a second file in the same folder (`petstore_components_minimal.json`) via:
```
"$ref": "./petstore_components_minimal.json#/components/schemas/Pet"
```
Kiota tries to load the components file from the **parent directory** instead of the specification file’s directory. This breaks `kiota show` and `kiota generate` flows. On Windows (PowerShell) the same layout works as expected.
This behavior is not affected by using JSON vs YAML specs.
### Expected behavior
Kiota should resolve references correctly on any platform.
### How to reproduce
**Folder layout**
```
openapi/
petstore_minimal.json
petstore_components_minimal.json
```
From the `openapi` folder run `kiota show`:
```bash
kiota show -d petstore_minimal.json
```
which shows the following error:
```
crit: Kiota.Builder.KiotaBuilder[0]
error showing the description: Could not find file '/Users/username/petstore_components_minimal.json'.
```
It can be seen that Kiota expects the components file outside of the `openapi` folder.
### Open API description file
## petstore_minimal.json
```json
{
"openapi": "3.0.0",
"info": {
"version": "1.0.0",
"title": "Swagger Petstore",
"license": {
"name": "MIT"
}
},
"servers": [
{
"url": "http://petstore.swagger.io/v1"
}
],
"paths": {
"/pets/{petId}": {
"get": {
"summary": "Info for a specific pet",
"operationId": "showPetById",
"tags": [
"pets"
],
"parameters": [
{
"name": "petId",
"in": "path",
"required": true,
"description": "The id of the pet to retrieve",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Expected response to a valid request",
"content": {
"application/json": {
"schema": {
"$ref": "./petstore_components_minimal.json#/components/schemas/Pet"
}
}
}
},
"default": {
"description": "unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "./petstore_components_minimal.json#/components/schemas/Error"
}
}
}
}
}
}
}
}
}
```
## petstore_components_minimal.json
```json
{
"openapi": "3.0.0",
"info": {
"version": "1.0.0",
"title": "Swagger Petstore components",
"license": {
"name": "MIT"
}
},
"paths": {},
"components": {
"schemas": {
"Pet": {
"type": "object",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "integer",
"format": "int64"
},
"name": {
"type": "string"
},
"tag": {
"type": "string"
}
}
},
"Error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"format": "int32"
},
"message": {
"type": "string"
}
}
}
}
}
}
```
### Kiota Version
1.29.0+c21ebceb977bc33def3d8a9e5237b798a7b962b6
### Latest Kiota version known to work for scenario above?(Not required)
_No response_
### Known Workarounds
For docker runs, mapping the ref'd files differently works for simple definitions:
```dockerfile
docker run \
-v "${PWD}"/openapi/petstore_minimal.json:/app/openapi/petstore_minimal.json \
-v "${PWD}"/openapi/petstore_components_minimal.json:/app/petstore_components_minimal.json \
mcr.microsoft.com/openapi/kiota show --openapi /app/openapi/petstore_minimal.json \
```
### Configuration
Following configurations do not work:
- macOS Tahoe 26.2 with zsh 5.9
- Docker Image: mcr.microsoft.com/openapi/kiota:1.29.0
Following configuration does work:
- Windows 11 with PowerShell 7.5.4
### Debug output
```
dbug: Kiota.Builder.KiotaBuilder[0]
kiota version 1.29.0
info: Kiota.Builder.KiotaBuilder[0]
loaded description from local source
dbug: Kiota.Builder.KiotaBuilder[0]
step 1 - reading the stream - took 00:00:00.0036811
crit: Kiota.Builder.KiotaBuilder[0]
error showing the description: Could not find file '/Users/username/petstore_components_minimal.json'.
```
### Other information
_No response_
Contributor guide
Research direction
Start by reproducing the issue with petstore_minimal.json and petstore_components_minimal.json using `kiota show -d petstore_minimal.json`, then compare local $ref resolution on macOS and in the Docker image. Trace the file-loading path from the `kiota show` entry point; done means same-folder relative references resolve correctly for both `show` and `generate` across the reported environments.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- docker
- Domain
- tooling
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100