fix: normalize explicit self-file $ref to internal pointer #2356

vadyvas · 2025-10-09T13:23:52Z

What/Why/How?

Normalize explicit self-file $ref to local internal pointers during bundling and avoid external loading for self-references in resolver.

swagger: '2.0'
info:
  version: '2021-09-01'
  title: Test
paths:
  /test:
    get:
      operationId: Test_Operation
      parameters:
        - $ref: 'test-api.yaml#/parameters/myParam'
parameters:
  myParam:
    name: myParam
    in: query
    type: string

Becomes:

paths:
  /test:
    get:
      parameters:
        - $ref: '#/parameters/myParam'

Reference

fix #1597

Testing

Unit tests: added to packages/core/src/__tests__/bundle.test.ts
E2E: added __tests__/bundle/self-file-ref-normalization.
Existing suites pass locally.

Screenshots (optional)

Check yourself

Code changed? - Tested with Redoc/Realm/Reunite (internal)
All new/updated code is covered by tests
New package installed? - Tested in different environments (browser/node)
Documentation update considered

Security

The security impact of the change has been considered
Code follows company security practices and guidelines

changeset-bot · 2025-10-09T13:23:56Z

🦋 Changeset detected

Latest commit: 83c545d

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
@redocly/openapi-core	Patch
@redocly/cli	Patch
@redocly/respect-core	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

github-actions · 2025-10-09T13:25:41Z

Command	Mean [s]	Min [s]	Max [s]	Relative
`redocly lint packages/core/src/benchmark/benches/rebilly.yaml`	1.406 ± 0.017	1.384	1.441	1.00
`redocly-next lint packages/core/src/benchmark/benches/rebilly.yaml`	1.414 ± 0.032	1.378	1.462	1.01 ± 0.03

…ncAPI 2, and AsyncAPI 3

.changeset/curly-tools-tap.md

tatomyr

Left a couple of minor suggestions. Also, could you modify some tests to first point to another file and then use self reference inside of it (just to be sure it works not only for root files)?

tatomyr · 2025-10-10T06:50:35Z

__tests__/bundle/self-file-ref-normalization/openapi.yaml

+  license:
+    name: MIT
+servers:
+  - url: http://example.com
+security: []


Please keep the test description minimal to only showcase the issue.

You don't need license, summary, operationId.

tatomyr · 2025-10-10T06:51:41Z

__tests__/bundle/self-file-ref-normalization/redocly.yaml

+extends:
+  - recommended


What do you need this for?

tatomyr · 2025-10-10T07:07:32Z

packages/core/src/__tests__/fixtures/self-file-refs/async2.yaml

+  title: AsyncAPI 2 self-file ref
+  version: '1.0.0'
+channels:
+  c:


Could you use the naming consistently here and in other tests (big/small letters; using/not using number)? Preferably something like we already use in our examples (TestChannel/foo/...).

tatomyr · 2025-10-10T08:41:13Z

One more thing: please make sure to test cases mentioned in this comment.

…r OAS2 and AsyncAPI 3

tatomyr

Approving with minor suggestions.

tatomyr · 2025-10-10T17:23:25Z

__tests__/bundle/self-file-ref-normalization/openapi.yaml

+  license:
+    name: MIT
+servers:
+  - url: http://example.com
+security: []


You don't need license, summary, operationId.

tatomyr · 2025-10-10T17:28:05Z

packages/core/src/bundle.ts

        }
+
+        // Normalize explicit self-file refs to internal pointer
+        if (ctx.location.source.absoluteRef === resolved.location.source.absoluteRef) {


Will it still work if we change it this way?

Suggested change

if (ctx.location.source.absoluteRef === resolved.location.source.absoluteRef) {

if (ctx.location.source === resolved.location.source) {

Or the location pointers are actually different?

@tatomyr moved the link replacement to the check below

tatomyr · 2025-10-14T06:50:23Z

packages/core/src/bundle.ts

          !dereference
        ) {
+          // Normalize explicit self-file refs to internal pointer
+          node.$ref = resolved.location.pointer;


Please check if comparing those values first will make performance better:

Suggested change

node.$ref = resolved.location.pointer;

if (node.$ref !== resolved.location.pointer) {

node.$ref = resolved.location.pointer;

}

this change improves performance, updated the pr

fix: normalize explicit self-file $ref to internal pointer

ccd9609

vadyvas added 2 commits October 9, 2025 16:51

tests: add tests for normalizing self-file explicit $ref in OAS2, Asy…

136b66d

…ncAPI 2, and AsyncAPI 3

chore: add changeset and remove unused fixture

86029c9

vadyvas marked this pull request as ready for review October 9, 2025 14:17

vadyvas requested review from a team as code owners October 9, 2025 14:17

JLekawa reviewed Oct 9, 2025

View reviewed changes

.changeset/curly-tools-tap.md Outdated Show resolved Hide resolved

Update .changeset/curly-tools-tap.md

1ec6e22

JLekawa approved these changes Oct 9, 2025

View reviewed changes

tatomyr reviewed Oct 10, 2025

View reviewed changes

tests: update self-file reference normalization tests and fixtures fo…

06355bd

…r OAS2 and AsyncAPI 3

tatomyr approved these changes Oct 10, 2025

View reviewed changes

vadyvas added 2 commits October 13, 2025 14:56

fix: simplify self-file reference check

2026f56

Merge branch 'main' into fix/core-self-file-ref-normalization

c28e6a4

tatomyr reviewed Oct 14, 2025

View reviewed changes

fix: ensure self-file reference is updated only when necessary

83c545d

tatomyr approved these changes Oct 14, 2025

View reviewed changes

vadyvas merged commit 26e0206 into main Oct 14, 2025
36 checks passed

vadyvas deleted the fix/core-self-file-ref-normalization branch October 14, 2025 10:14

	if (ctx.location.source.absoluteRef === resolved.location.source.absoluteRef) {
	if (ctx.location.source === resolved.location.source) {

		extends:
		- recommended

fix: normalize explicit self-file $ref to internal pointer #2356

fix: normalize explicit self-file $ref to internal pointer #2356

Uh oh!

Conversation

vadyvas commented Oct 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What/Why/How?

Reference

Testing

Screenshots (optional)

Check yourself

Security

Uh oh!

changeset-bot bot commented Oct 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

github-actions bot commented Oct 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

tatomyr left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tatomyr commented Oct 10, 2025

Uh oh!

tatomyr left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

vadyvas commented Oct 9, 2025 •

edited

Loading

changeset-bot bot commented Oct 9, 2025 •

edited

Loading

github-actions bot commented Oct 9, 2025 •

edited

Loading