fix: Fix relative references inside external path items (#1948, #2066)

[ewaostrowska]

Pull Request

Description

When a path item is defined in an external file, that file can contain references to other files. Those nested references are relative paths, so they should be resolved relative to the external file's own location.

The parser was resolving them relative to the root document instead. If your external file lived in product/product-api.yaml and referenced a sibling product-components.yaml, the parser went looking for product-components.yaml at the root level, failed, and either threw an error or silently dropped the component.

Root causes

1. isAbsoluteRef misclassified bare filenames as absolute

product-components.yaml does not start with a dot, so the old code treated it as absolute and skipped rebasing entirely. A URI is only absolute when it has a scheme (https://, file://, etc.).

2. computeRelativeRef bailed out immediately for ./ refs

The fix uses URI.resolve(), which is how browsers resolve relative links. Given a base and a relative reference, it produces the correct result including normalizing dot segments:

Example — issue #2066:

• base: ./sub-dir/params.json
• ref: ./sub-dir2/pagination_params_1.json
• resolved: ./sub-dir/sub-dir2/pagination_params_1.json

Example — issue #1948:

• base: product/product-api.yaml
• ref: product-components.yaml#/components/parameters/param1
• resolved: product/product-components.yaml#/components/parameters/param1

3. Schemas and examples need a guard against double-rebasing

ExternalRefProcessor already rebases schema and example refs when it loads an external path item. If PathsProcessor then ran the full computeRef on those refs a second time, ./-prefixed schemas would get rebased twice and end up wrong.

The new computePreprocessedRef method is used for schemas and examples. It handles ../ refs and fragment-only refs, but leaves ./ refs and bare names alone (already handled upstream). Parameter $refs do not go through ExternalRefProcessor, so they still use the full computeRef.

What is not covered

The separate response-header behaviors reported in #2060 are outside the scope of this PR.

Fixes: #2066 and #1948

Type of Change

• 🐛 Bug fix
• ✨ New feature
• ♻️ Refactor (non-breaking change)
• 🧪 Tests
• 📝 Documentation
• 🧹 Chore (build or tooling)

Checklist

• I have added/updated tests as needed
• I have added/updated documentation where applicable
• The PR title is descriptive
• The code builds and passes tests locally
• I have linked related issues (if any)

Screenshots / Additional Context