Fails to resolve local relative $ref references to external files on macOS (zsh) and official Kiota Docker container

[bst-wd]

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:

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

{
    "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

{
  "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:

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