[Bug]: OpenAPI 3.1 same-file $ref resolution reports illegal path when raw local path contains spaces

[salockhart]

Description

OpenAPIV3Parser.readLocation(...) parses an OpenAPI 3.1 document from a raw local filesystem path containing spaces, but same-file $ref resolution records an Illegal character in path error.

The spec is a single file. It does not use sibling or external spec files.

The failing case is a response $ref within the same OpenAPI document:

paths:
  /examples:
    get:
      responses:
        '200':
          $ref: '#/components/responses/ExampleResponse'
components:
  responses:
    ExampleResponse:
      description: OK
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Example'

When the file is parsed from a raw path like:

/tmp/openapi path with spaces.../openapi.yaml

the parser reports Illegal character in path.

Affected Version

Current master / 2.1.46-SNAPSHOT.

Earliest version the bug appears in (if known):
I have also reproduced similar raw-path-with-spaces behavior against released 2.1.x versions, so this does not appear to be a recent regression.

Steps to Reproduce

1. Create an OpenAPI 3.1 file in a directory whose path contains spaces.
2. Include a same-file response $ref, such as #/components/responses/ExampleResponse.
3. Parse it with OpenAPIV3Parser.readLocation(...) using the raw filesystem path.

Minimal repro branch:

https://github.com/salockhart/swagger-parser/tree/feat/openapi31-space-path-ref-repro

Relevant commit:

d47f782d test: reproduce OpenAPI 3.1 path with spaces ref issue

Focused test command:

mvn -pl modules/swagger-parser-v3 -am \
  -Dtest=OpenAPIV31ParserUriTest#resolveSameFileReferenceFromRawPathWithSpaces \
  -DfailIfNoTests=false \
  -Dsurefire.failIfNoSpecifiedTests=false \
  test

Expected Behavior

A raw local path accepted by OpenAPIV3Parser.readLocation(...) should not produce an Illegal character in path error while resolving same-file OpenAPI 3.1 references.

Alternatively, if raw local paths are not intended to be supported when they contain spaces, the parser should fail clearly or document that callers must pass a URI-safe file URL.

Actual Behavior

The parser returns an OpenAPI model, but the parse result contains an error message like:

Illegal character in path at index ...: /tmp/openapi path with spaces.../openapi.yaml

The error is emitted while resolving same-file OpenAPI 3.1 refs.

Logs / Stack Traces

The focused repro test currently fails with:

java.lang.AssertionError: expected [null] but found [Illegal character in path at index ...: /tmp/openapi path with spaces.../openapi.yaml]

The stack trace points through OpenAPI 3.1 reference resolution, including:

io.swagger.v3.parser.reference.Visitor.readURI
io.swagger.v3.parser.reference.ReferenceVisitor.resolveRef
io.swagger.v3.parser.reference.ReferenceVisitor.visitResponse
io.swagger.v3.parser.reference.OpenAPIDereferencer31.dereference
io.swagger.v3.parser.OpenAPIV3Parser.readLocation

Environment

• Java version: reproduced locally with Temurin 25.0.3
• Build tool: Maven
• OS: macOS

Additional Context

Adjacent but not exact existing issues:

• StringIndexOutOfBounds exceptions with relative server urls when loading from a file path that includes spaces #1572
• openapi 3.1: Illegal character in fragment when path reference contains paramneters #2159
• File Path Issue on Windows with OAS 3.1 - Illegal character in opaque part at index #2136

Checklist

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