Description

Same-document $refs in OpenAPI 3.1 definitions fail to dereference when the base URI has a non-http(s) scheme. Every $ref throws Could not resolve reference: Evaluation failed on URI: "<baseDoc>#/components/...".

The dereference visitor evaluates a $ref as a JSON Schema URI first, and that evaluation throws EvaluationJsonSchemaUriError for plain pointer refs under any base. The recovery in the catch block (JSON Pointer / $anchor evaluation) is gated on isURL, which is false when no registered resolver can read the base scheme, so non-http(s) bases never reach it. A same-document reference doesn't need a resolver at all, the document is already in the ReferenceSet. This change allows the recovery for same-document references regardless of the base scheme.

References to other documents with unresolvable schemes keep the current behavior, the $ref-urn-unresolvable fixtures pass unchanged.

Motivation and Context

This breaks swagger-ui when embedded in runtimes that are not served over http(s). Electron loads the renderer over file://, swagger-ui derives baseDoc from document.baseURI, and every OpenAPI 3.1 definition with internal $refs fails to render. OpenAPI 3.0 is unaffected since it resolves through a different strategy.

Related downstream reports: swagger-api/swagger-ui#9922, swagger-api/swagger-ui#10599.

How Has This Been Tested?

Added a regression test in test/resolver/strategies/openapi-3-1-apidom: resolving a 3.1 petstore with baseDoc: 'file:///app/index.html' fails on main and passes with this change.

npm run test:unit passes. The only failures are in test/execute/openapi-3-2.js, which fail identically on a clean main checkout.

Also verified in the originating environment, an Electron app rendering OpenAPI 3.1 definitions through swagger-ui-react over file://.

Screenshots (if appropriate):

Types of changes

• No code changes (changes to documentation, CI, metadata, etc)
• Dependency changes (any modification to dependencies in package.json)
• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

• My code follows the code style of this project.
• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I have added tests to cover my changes.
• All new and existing tests passed.