[Bug]: References to elements within jar files cannot be resolved

[TijsSchoneveld]

Description

When an openapi spec is contained in a jar file and read using a jar URI (e.x. jar:file:/spec.jar!/openapi.yaml), references to elements within that spec cannot be resolved.

This only happens when using OpenAPI 3.1 and with ParseOptions#setResolve enabled.

Affected Version

Version 2.1.37

Earliest version the bug appears in (if known):
As far as I can tell this has been an issue since jar URI were supported in 2.0.31

Steps to Reproduce

Minimal openapi spec:

openapi: 3.1.0
servers:
  - url: /
info:
  description: It doesn't work.
  version: 1.0.0
  title: My API
paths:
  /innerRefPath:
    get:
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dog'
components:
  schemas:
    Dog:
      properties:
        name:
          type: string

1. Put the openapi spec in a jar file.
2. Attempt to parse the spec using OpenAPIV3Parser#readLocation with resolve option set to true.
3. The SwaggerParseResult contains an error message and an error log is present.

Expected Behavior

The spec should parse without errors.

Actual Behavior

The issue happens in ReferenceVisitor#resolveSchemaRef when the baseURI is computed.
Because a jar URI is an opaque URI, when it is passed to ReferenceUtils#resolve along with the reference fragment it will only return the fragment without the base URI. When that fragment is then passed to ReferenceUtils#toBaseURI it will lack a scheme or a scheme specific part so it will return a empty string.

That empty baseURI is then passed to ReferenceVisitor#parse which will return a JsonNode of null. That json node will later be used to try to resolve the reference with ReferenceUtils#jsonPointerEvaluate which will throw an exception because the json tree is null.

Logs / Stack Traces

The following error is logged during parsing:

[main] ERROR io.swagger.v3.parser.reference.ReferenceVisitor - Error resolving schema #/components/schemas/Dog
java.lang.RuntimeException: Could not find /components/schemas/Dog in contents of #/components/schemas/Dog
	at io.swagger.v3.parser.reference.ReferenceVisitor.resolveSchemaRef(ReferenceVisitor.java:266)
	at io.swagger.v3.parser.reference.ReferenceVisitor.visitSchema(ReferenceVisitor.java:153)
	at io.swagger.v3.parser.reference.OpenAPI31Traverser.traverseSchema(OpenAPI31Traverser.java:801)
	at io.swagger.v3.parser.reference.OpenAPI31Traverser.traverseMediaType(OpenAPI31Traverser.java:603)
	at io.swagger.v3.parser.reference.OpenAPI31Traverser.traverseMap(OpenAPI31Traverser.java:947)
	at io.swagger.v3.parser.reference.OpenAPI31Traverser.traverseResponse(OpenAPI31Traverser.java:299)
	at io.swagger.v3.parser.reference.OpenAPI31Traverser.traverseMap(OpenAPI31Traverser.java:947)
	at io.swagger.v3.parser.reference.OpenAPI31Traverser.traverseResponses(OpenAPI31Traverser.java:270)
	at io.swagger.v3.parser.reference.OpenAPI31Traverser.traverseOperation(OpenAPI31Traverser.java:237)
	at io.swagger.v3.parser.reference.OpenAPI31Traverser.traversePathItem(OpenAPI31Traverser.java:394)
	at io.swagger.v3.parser.reference.OpenAPI31Traverser.traverseMap(OpenAPI31Traverser.java:947)
	at io.swagger.v3.parser.reference.OpenAPI31Traverser.traversePaths(OpenAPI31Traverser.java:197)
	at io.swagger.v3.parser.reference.OpenAPI31Traverser.traverseOpenApi(OpenAPI31Traverser.java:124)
	at io.swagger.v3.parser.reference.OpenAPI31Traverser.traverse(OpenAPI31Traverser.java:65)
	at io.swagger.v3.parser.reference.OpenAPIDereferencer31.dereference(OpenAPIDereferencer31.java:74)
	at io.swagger.v3.parser.OpenAPIV3Parser.resolve(OpenAPIV3Parser.java:230)
	at io.swagger.v3.parser.OpenAPIV3Parser.readContents(OpenAPIV3Parser.java:183)
	at io.swagger.v3.parser.OpenAPIV3Parser.readLocation(OpenAPIV3Parser.java:
	...

Environment

• Java version: 11
• Build tool: 3.9.11
• OS: macOS Sequoia 15.6.1

Additional Context

Javadoc for URI.resolve(URI) specifically:

If the given URI is already absolute, or if this URI is opaque, then the given URI is returned.

Checklist

• I have searched the existing issues and this is not a duplicate.
• I have provided sufficient information for maintainers to reproduce the issue.