Skip to content

fix: Rebase relative refs inside external path items only once (#2418) - #2419

Open
ericschlarmann wants to merge 2 commits into
swagger-api:masterfrom
ericschlarmann:fix-nested-path-item-relative-refs
Open

ericschlarmann wants to merge 2 commits into
swagger-api:masterfrom
ericschlarmann:fix-nested-path-item-relative-refs

Conversation

@ericschlarmann

@ericschlarmann ericschlarmann commented Nov 3, 2026 •

Copy link
Copy Markdown

Pull Request

Description

Fixes a regression in 2.1.48, still present in 2.1.49. With the root document in a subdirectory, a relative schema or example $ref inside an external path item two directories down was rebased twice. ../../domain/sub/schemas.yaml became ../domain/domain/sub/schemas.yaml, and resolving it failed with Unable to load RELATIVE ref.

ExternalRefProcessor.processPathItem already rebases these refs onto the root document. PathsProcessor.updateRefs then resolved them again against the path item's file, and computePreprocessedRef only recognizes a rebased ref when it does not start with a dot or starts with ./. A rebased ref can start with ../ once the root document is not at the top.

ExternalRefProcessor now records the schemas and examples it rebased (an identity set, scoped to the processor instance PathsProcessor owns), and PathsProcessor.updateRefs leaves those alone. Every other ref takes the same path as before, so the existing computeRef / computePreprocessedRef tests are unchanged.

Fixes: #2418

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

New data-driven test PathsProcessorTest.testRefInPathItemBelowSubdirectoryEntryIsRebasedOnce with resources in src/test/resources/path-item-below-subdirectory-entry/: root documents in api/, path items in domain/sub/. It uses one root document per case, because the first ref that fails to load stops the resolution of every later one.

The eleven cases that processPathItem rebases fail on master and pass with the fix:

  • a ../../domain/sub/ ref,
  • a ./ ref,
  • a bare schemas.yaml ref,
  • a ref into another directory (../../shared/),
  • a nested property ref,
  • a response example,
  • an operation parameter schema,
  • an array items ref,
  • an allOf ref,
  • an anyOf ref,
  • a oneOf ref.

On master they come out as ../domain/domain/sub/... or ../domain/shared/.... 2.1.47 also rebased them twice, but left the joined path un-normalized (../domain/sub/../domain/sub/schemas.yaml), which the .. fallback in RefUtils.readExternalRef recovered.

Three cases that only PathsProcessor rebases (a path-level parameter schema, a request body example and a callback request body schema) pass on both. They pin that every other ref is still rebased once. Their refs go up one directory only, because the .. fallback would also load a ../../ ref that was never rebased.

Full build mvn test on JDK 17: all modules green.

Also checked against a larger real-world multi-file spec set with three root documents, generating with openapi-generator 7.26.0 and this build swapped in:

  • The root document at the top of the tree gives byte-identical output to stock 2.1.48.
  • The other two, including the one in a subdirectory (the failing case), give byte-identical output to stock 2.1.47.
  • With openapi-generator 7.27.0, the subdirectory root document generates without errors again.

ExternalRefProcessor.processPathItem rebases the relative schema and
example refs of an external path item onto the root document. Afterwards
PathsProcessor.updateRefs resolves the same refs again against the path
item's file. computePreprocessedRef skips a ref only when it does not
start with a dot or starts with "./". The second resolution is therefore
a no-op for an entry document at the root, and also for path items one
directory down. It can break once the rebased ref starts with "../":
with the entry in a subdirectory and the path item two directories down,
../../domain/sub/schemas.yaml becomes ../domain/domain/sub/schemas.yaml
("Unable to load RELATIVE ref"). Before 2.1.48 the unnormalized
concatenation of computeRelativeRef left
../domain/sub/../domain/sub/schemas.yaml, which the ".." fallback in
RefUtils.readExternalRef happened to recover.

ExternalRefProcessor now records the schemas and examples it rebased,
and PathsProcessor leaves those alone. Every other ref is rebased as
before.

// One root document per case: the first ref that fails to load stops the resolution of every later one.
@DataProvider
public Object[][] refsInPathItemBelowSubdirectoryEntry() {

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

suggestion: The data provider is missing a few ref shapes.

It covers direct $ref, a nested property, parameters, and request and response examples. But the guard sits in a recursive method that also walks allOf, anyOf/oneOf, array items and callbacks, and a ref reached through one of those branches might not be marked.

Tests for items: {$ref: ...}, allOf: [{$ref: ...}] and a callback body schema would cover them.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added rows for items, allOf, anyOf, oneOf and a callback body schema.

protected void updateRefs(Schema model, String pathRef) {
if(model.get$ref() != null) {
model.set$ref(computePreprocessedRef(model.get$ref(), pathRef));
if(!externalRefProcessor.isRebasedOntoRootDocument(model)) {

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

question: Are discriminator mappings on composed schemas still consistent with this guard?

Say ExternalRefProcessor rebased the inner $ref and left the matching discriminator.mapping value alone. Then the mapping points somewhere other than the ref it describes.

A test row with a oneOf and a discriminator.mapping, inside an external path item below a subdirectory, would settle it.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The guard can't split them: PathsProcessor only rewrites a mapping value together with its ref. Mapping values in a path item's request body, response and parameter schemas are never rebased at all, but that's an older bug, also on master, independent of this PR.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's #2406, fixed in #2407.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Clear, thanks.

protected void updateRefs(Schema model, String pathRef) {
if(model.get$ref() != null) {
model.set$ref(computePreprocessedRef(model.get$ref(), pathRef));
if(!externalRefProcessor.isRebasedOntoRootDocument(model)) {

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nitpick: The nested if here is right. Folding it into the outer condition with && sends a marked schema into the else if (properties) branches.

Someone cleaning up the code might make that change. Worth a comment so it stays nested:
// nested on purpose: a marked schema must not fall through to the sibling branches

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added.

@diegourban diegourban left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I ran into this myself after upgrading openapi-generator to 7.27.0, which bundles swagger-parser 2.1.48.

The proposed fix looks right to me. I would like the discriminator mapping question on composed schemas answered, or covered by a test, before this merges.

Adds data provider rows for refs reached through array items, allOf,
anyOf and oneOf, which processPathItem rebases and marks; all four fail
on master. Adds a callback request body schema, which only
PathsProcessor rebases.

The rows for refs only PathsProcessor rebases now go up one directory.
With "../../" the ".." fallback in RefUtils.readExternalRef loaded the
ref even when it was never rebased, so those rows could not catch a
missing rebase.

Comments the nested if in PathsProcessor.updateRefs(Schema): folded
into the outer condition, a marked schema would fall through to the
else-if branches.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Bug]: 2.1.48 rebases a relative $ref inside an external path item twice when the root document is in a subdirectory

2 participants