[BUG] [openapi-yaml] Inconsistent Relative Reference Resolution in Nested Schema Contexts

Bug Report Checklist

• Have you provided a full/minimal spec to reproduce the issue?
• Have you validated the input using an OpenAPI validator?
• Have you tested with the latest master to confirm the issue still exists? (I tried by the latest docker image)
• Have you searched for related issues/PRs?
• What's the actual output vs expected output?
• [Optional] Sponsorship to speed up the bug fix or feature request (example)

Description

OpenAPI Generator incorrectly resolves relative $ref paths in schema files when they are referenced through nested contexts (like additionalProperties). The reference resolution context switches from file-relative to root-relative depending on the nesting level, causing build failures when using standard file-relative references.

This creates inconsistent behavior where:

• References from path files work correctly using file-relative paths (../components/schemas/...)
• References from schema files fail when using file-relative paths (NestedData.yaml)

This violates the OpenAPI 3.0 specification where all relative references should be resolved from the containing file's location.

openapi-generator version

• 7.14.0 (latest stable): ❌ Bug reproduced (By Docker)
• 8.0.0-SNAPSHOT (2024-07-27): ❌ Bug still exists (By Maven snapshots)

OpenAPI declaration file content or url

root.yaml:

openapi: 3.0.2
info:
  title: Relative Reference Bug Reproduction
  version: 1.0.0
servers:
  - url: http://localhost:3000
paths:
  /api/example:
    $ref: ./paths/example.yaml#/operations

paths/example.yaml:

operations:
  get:
    summary: Example API endpoint
    operationId: getExample
    responses:
      200:
        description: Success response
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExampleResponse'
components:
  schemas:
    ExampleResponse:
      type: object
      properties:
        data:
          $ref: ../components/schemas/ExampleData.yaml

components/schemas/ExampleData.yaml:

type: object
description: Schema with relative reference that fails
additionalProperties:
  type: object
  properties:
    nested:
      $ref: NestedData.yaml

components/schemas/NestedData.yaml:

type: object
properties:
  value:
    type: string

Generation Details

docker run --rm -v $(pwd):/app -w /app \
  openapitools/openapi-generator-cli:v7.14.0 generate \
  -i ./root.yaml \
  -g openapi-yaml \
  -o resolved

Steps to reproduce

1. Create the file structure above
2. Run the generation command
3. Observe the error: Unable to load RELATIVE ref: NestedData.yaml path: /app/.

Expected behavior: All relative references should resolve from their containing file's directory.

Actual behavior: Schema-level references are resolved from the root directory instead of the file's directory.

Working workaround (demonstrating the inconsistency):

# In components/schemas/ExampleData.yaml, change:
$ref: NestedData.yaml
# To:
$ref: ./components/schemas/NestedData.yaml

Related issues/PRs

• the simplest reproducible repository https://github.com/MokkeMeguru/oapi3.0-relative-resolve
• related issue I think https://github.com/OpenAPITools/openapi-generator/issues/11151

Suggest a fix

I think the method RefUtils.readExternalRef() causes this problem...

Reproduce the issue with root.yaml, the paths/example.yaml and components/schemas files using the provided Docker generation command. Then inspect RefUtils.readExternalRef() and the related reference-resolution path; done means nested references resolve relative to their containing file and openapi-yaml generation succeeds without the reported error.