fix: error `can't resolve $ref` when `components.parameters` has a ref to the `components.schemas` #2407

AlbinaBlazhko17 · 2025-11-04T15:01:52Z

What/Why/How?

The issue happens when parameter has a reference to schemas and remove-unused-components decorator provided in redocly.yaml.
This PR contains the global fix, nothing changes inside remove-unused-components decorator, because the issue happens in all decorators/rules, which are using Parameters visitor.

Reference

Resolves #2350

Testing

Ran tests and created new for this specific case.

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-11-04T15:01:56Z

🦋 Changeset detected

Latest commit: 7b0d730

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-11-04T15:03:51Z

Command	Mean [s]	Min [s]	Max [s]	Relative
`redocly lint resources/rebilly.yaml`	1.446 ± 0.017	1.417	1.476	1.01 ± 0.02
`redocly-next lint resources/rebilly.yaml`	1.425 ± 0.019	1.395	1.457	1.00

github-actions · 2025-11-04T15:04:01Z

Coverage Report

Status	Category	Percentage	Covered / Total
🟢	Lines	78.73% (🎯 78%)	5854 / 7435
🟢	Statements	78.17% (🎯 78%)	6049 / 7738
🟢	Functions	81.89% (🎯 81%)	1203 / 1469
🟢	Branches	70.94% (🎯 70%)	4053 / 5713

File Coverage

File	Stmts	Branches	Functions	Lines	Uncovered Lines
Changed Files
packages/core/src/walk.ts	99.32%	97.01%	100%	99.28%	149-152
packages/core/src/bundle/bundle-visitor.ts	75.22%	71.05%	100%	75.22%	24, 28-36, 41-49, 56, 65, 73, 78-80, 138-150, 179-180, 212

Generated in workflow #8002 for commit 7b0d730 by the Vitest Coverage Report Action

.changeset/happy-chairs-drop.md

tatomyr

Please also test this change in Realm/Redoc before merging as it affects the bundler.

AlbinaBlazhko17 · 2025-11-05T16:41:26Z

Please also test this change in Realm/Redoc before merging as it affects the bundler.

Tested changes in Realm/Redoc.

Co-authored-by: Jacek Łękawa <[email protected]>

docs/@v2/commands/bundle.md

tests/e2e/bundle/parameters-reference-to-schemas/parameters.yaml

tests/e2e/bundle/parameters-reference-to-schemas/snapshot.txt

jeremyfiel · 2025-11-05T20:46:08Z

did you check if this works for other components? headers, pathItems in 3.1.x, examples, requestBodies, responses

AlbinaBlazhko17 · 2025-11-05T21:08:55Z

@jeremyfiel Yeah, you are right, need to test with all cases, i will test it tomorrow. At the first glance, everything looks good and all users, that reported this bug faced it in parameters. I thought, that we covered a lot of cases in test and if all tests passes the fixes work correctly.

.changeset/happy-chairs-drop.md

This reverts commit 3a43128.

AlbinaBlazhko17 · 2025-11-06T16:04:33Z

@jeremyfiel Great point, i implemented new fix for this case and tested for all type of components, provided in remove-unused-components decorator.

Co-authored-by: Andrew Tatomyr <[email protected]>

tatomyr · 2025-11-07T07:59:55Z

packages/core/src/bundle/bundle-visitor.ts

+            resolveBundledComponent(node, resolved, ctx.location.source.absoluteRef);
+            // Also register from root document location if this is an external ref
+            // This ensures refs inside bundled components can be resolved when visited later
+            if (ctx.location.source !== rootDocument.source) {


Could you add a test to demonstrate how would such cases look like?

AlbinaBlazhko17 force-pushed the fix/cant-resolve-error-in-remove-unused-components branch from 4631f22 to ec8a31c Compare November 4, 2025 15:10

AlbinaBlazhko17 marked this pull request as ready for review November 4, 2025 15:48

AlbinaBlazhko17 requested review from a team as code owners November 4, 2025 15:48

JLekawa reviewed Nov 4, 2025

View reviewed changes

.changeset/happy-chairs-drop.md Outdated Show resolved Hide resolved

JLekawa approved these changes Nov 4, 2025

View reviewed changes

JLekawa reviewed Nov 4, 2025

View reviewed changes

.changeset/happy-chairs-drop.md Outdated Show resolved Hide resolved

AlbinaBlazhko17 self-assigned this Nov 5, 2025

tatomyr approved these changes Nov 5, 2025

View reviewed changes

AlbinaBlazhko17 and others added 8 commits November 5, 2025 18:42

fix: can't resolve ref error when using

082d968

feat: add test for the specific case

fc7f396

feat: add changeset

982edb9

chore: add comment

b6843a8

chore: remove comment

1a8fea3

Update .changeset/happy-chairs-drop.md

673289f

Co-authored-by: Jacek Łękawa <[email protected]>

Update .changeset/happy-chairs-drop.md

d03375a

chore: add docs for the bundle command

06df369

AlbinaBlazhko17 force-pushed the fix/cant-resolve-error-in-remove-unused-components branch from 7c12980 to 06df369 Compare November 5, 2025 16:42

jeremyfiel reviewed Nov 5, 2025

View reviewed changes

docs/@v2/commands/bundle.md Outdated Show resolved Hide resolved

jeremyfiel reviewed Nov 5, 2025

View reviewed changes

tests/e2e/bundle/parameters-reference-to-schemas/parameters.yaml Show resolved Hide resolved

jeremyfiel reviewed Nov 5, 2025

View reviewed changes

tests/e2e/bundle/parameters-reference-to-schemas/snapshot.txt Show resolved Hide resolved

AlbinaBlazhko17 added 3 commits November 5, 2025 22:49

docs: change naming

842eba1

fix: add to param name and change snapshot

d7d1092

chore: change order

e4acbe3

tatomyr reviewed Nov 6, 2025

View reviewed changes

.changeset/happy-chairs-drop.md Outdated Show resolved Hide resolved

AlbinaBlazhko17 added 4 commits November 6, 2025 14:34

feat: implement new fix to cover parameters + other components

3a43128

Revert "feat: implement new fix to cover parameters + other components"

1219167

This reverts commit 3a43128.

feat: implement new fix to cover parameters + other components

5159619

feat: implement new fix to cover parameters + other components

9744269

Update .changeset/happy-chairs-drop.md

bc4d481

Co-authored-by: Andrew Tatomyr <[email protected]>

tatomyr reviewed Nov 7, 2025

View reviewed changes

feat: implement proper logic for decorator and bundle-visitor

40dfc66

AlbinaBlazhko17 requested a review from tatomyr November 11, 2025 12:49

AlbinaBlazhko17 added 8 commits November 11, 2025 14:50

refactor: resolveBundledComponent location

1c4dc8a

fix: change in all places to make ref id from the root document

803c12c

chore: remove changes in decorator due to proper resolve

878586c

fix: ajv instance resolve ref and unit test snapshots

bb9e3e7

chore: revert previous fix

2379a4e

chore: revert tests

5d4f009

feat: add wrapper for resolve function with a default value

fac1645

refactor: override of the default arguments in resolve function

7b0d730

fix: error can't resolve $ref when components.parameters has a ref to the components.schemas #2407

Are you sure you want to change the base?

fix: error can't resolve $ref when components.parameters has a ref to the components.schemas #2407

Uh oh!

Conversation

AlbinaBlazhko17 commented Nov 4, 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 Nov 4, 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 Nov 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

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

Uh oh!

Coverage Report

Uh oh!

Uh oh!

Uh oh!

tatomyr left a comment

Choose a reason for hiding this comment

Uh oh!

AlbinaBlazhko17 commented Nov 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Tested changes in Realm/Redoc.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jeremyfiel commented Nov 5, 2025

Uh oh!

AlbinaBlazhko17 commented Nov 5, 2025

Uh oh!

Uh oh!

AlbinaBlazhko17 commented Nov 6, 2025

Uh oh!

tatomyr Nov 7, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

fix: error `can't resolve $ref` when `components.parameters` has a ref to the `components.schemas` #2407

fix: error `can't resolve $ref` when `components.parameters` has a ref to the `components.schemas` #2407

AlbinaBlazhko17 commented Nov 4, 2025 •

edited

Loading

changeset-bot bot commented Nov 4, 2025 •

edited

Loading

github-actions bot commented Nov 4, 2025 •

edited

Loading

github-actions bot commented Nov 4, 2025 •

edited

Loading

AlbinaBlazhko17 commented Nov 5, 2025 •

edited

Loading