[Bug]: External schema resolution broken in OpenAPI 3.1 (works in 3.0)

Description

When parsing an OpenAPI 3.1 specification with external schema references (using $ref to separate YAML files), the getComponents().getSchemas() method returns null. The same specification works correctly when using OpenAPI 3.0.

Environment

• swagger-parser version: [2.1.37 latest one]
• OpenAPI version: 3.1.0
• Java version: [21 LTS]
• Operating System: macOS [26.2]

Expected Behavior

External schema references should be resolved and added to the components section, making them accessible via openAPI.getComponents().getSchemas(), just as they are in OpenAPI 3.0.

Actual Behavior

openAPI.getComponents().getSchemas() returns null when using OpenAPI 3.1, even with all resolution options enabled:

• setResolve(true)
• setResolveFully(true)
• setResolveResponses(true)

Sample Code

OpenAPI Specification (swagger.yaml)

openapi: 3.1.0
info:
  title: Backend
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.0

servers:
  - url: '{protocol}://{hostname}:{port}'
    variables:
      protocol:
        enum:
          - http
          - https
        default: http
      hostname:
        default: localhost
      port:
        default: '8080'

paths:
  /probe/info:
    get:
      tags:
        - health
      summary: info of the system
      operationId: probe.info
      security: []
      responses:
        200:
          description: system is up and running
          content:
            application/json:
              schema:
                $ref: 'schemas/health.yaml#/ProbeInfo'

External Schema File (schemas/health.yaml)

ProbeInfo:
  type: object
  properties:
    status:
      type: string
    version:
      type: string
  required:
    - status

Java Code

package com.vadaliya;

import io.swagger.parser.OpenAPIParser;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.parser.core.models.ParseOptions;
import io.swagger.v3.parser.core.models.SwaggerParseResult;

public class Main {
  public static void main(String[] args) {

    ParseOptions parseOptions = new ParseOptions();
    parseOptions.setResolve(true);
    parseOptions.setResolveResponses(true);
    parseOptions.setResolveFully(true);

    SwaggerParseResult result = new OpenAPIParser().readLocation(
      "/path/to/swagger.yaml", null, parseOptions);

    OpenAPI openAPI = result.getOpenAPI();

    if (result.getMessages() != null) {
      result.getMessages().forEach(System.err::println);
    }

    // Returns null for OpenAPI 3.1, works fine for OpenAPI 3.0
    System.out.println(openAPI.getComponents().getSchemas());
  }
}

Steps to Reproduce

1. Create an OpenAPI 3.1 specification with external schema references (as shown above)
2. Create the external schema file in a subdirectory
3. Parse the specification using swagger-parser with all resolution options enabled
4. Call openAPI.getComponents().getSchemas()
5. Observe that it returns null

Workaround

Changing the OpenAPI version from 3.1.0 to 3.0.0 in the specification resolves the issue, and schemas are properly populated in the components section.

Related Issues

This appears to be related to:

• #2079 - External components not added as shared components for OpenAPI 3.1
• #1950 - Parameter/Response $refs not resolving in OpenAPI 3.1

Additional Context

The schemas are defined in external files to maintain modularity and reusability across multiple API specifications. This pattern works perfectly with OpenAPI 3.0 but breaks with 3.1.

The external reference resolution seems to work differently in OpenAPI 3.1, and the parsed schemas are not being added to the components section as expected.

Question

Is this the intended behavior for OpenAPI 3.1, or is this a bug? If this is intended, what is the recommended approach for accessing externally referenced schemas in OpenAPI 3.1 specifications?

Start with OpenAPIParser.readLocation using the supplied OpenAPI 3.1 and external health.yaml examples, with ParseOptions resolution enabled. Compare the 3.1 path with 3.0 behavior and review related issues #2079 and #1950; the work is done when the externally referenced schema is available through openAPI.getComponents().getSchemas() and the behavior is covered by a regression test.