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

[Kavan72]

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:

• $ref to external component are not add as shared component for open API 3.1 but recreated for each usage #2079 - External components not added as shared components for OpenAPI 3.1
• [Bug] Parameter/Response $refs are not resolving in OpenAPI 3.1 definitions #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?

[Kavan72]

Root Cause Analysis

I've identified the issue in the codebase:

Problematic Function:
https://github.com/swagger-api/swagger-parser/blob/master/modules/swagger-parser-v3/src/main/java/io/swagger/v3/parser/OpenAPIV3Parser.java#L208

Related PR:
#1730

The issue appears to be in how the OpenAPIV3Parser handles external schema resolution for OpenAPI 3.1 specifications. The changes introduced in PR #1730 may have affected how external $ref schemas are processed and added to the components/schemas section.

[Kavan72]

My solutions is like this i don't know does it works or not

// Modify the 3.1 resolution path to USE ComponentsProcessor
if (result.getOpenAPI().getOpenapi() != null && result.getOpenAPI().getOpenapi().startsWith("3.1")) {
    if (StringUtils.isBlank(System.getenv(DISABLE_OAS31_RESOLVE))) {
        DereferencerContext dereferencerContext = new DereferencerContext(...);
        OpenAPIDereferencer dereferencer = dereferencers.iterator().next();
        dereferencer.dereference(dereferencerContext, dereferencers.iterator());
        
        // NEW: Also run ComponentsProcessor for component population
        ResolverCache cache = new ResolverCache(
            result.getOpenAPI(), auth, parentFileLocation, 
            new HashSet<>(), parseOptions
        );
        ComponentsProcessor componentsProcessor = 
            new ComponentsProcessor(result.getOpenAPI(), cache);
        componentsProcessor.processComponents();
    }
}

cc @frantuma

[dennisameling]

@Kavan72 thanks for the clear issue description. I was running into the same problem with one of my projects using the openapi-generator. I haven't tested your suggested solution, but found that the issue mainly stems from the fact that the OpenAPI31Traverser seemingly never got full support for external references when it was introduced.

Here's a PR that I can confirm fixes the issue that you reported. openAPI.getComponents().getSchemas() no longer returns null on the schema that you provided with the given parser options, but instead returns the ProbeInfo class as expected:

expand me

{ProbeInfo=class JsonSchema {
    class Schema {
        type: [object]
        format: null
        $ref: null
        description: null
        title: null
        multipleOf: null
        maximum: null
        exclusiveMaximum: null
        minimum: null
        exclusiveMinimum: null
        maxLength: null
        minLength: null
        pattern: null
        maxItems: null
        minItems: null
        uniqueItems: null
        maxProperties: null
        minProperties: null
        required: [status]
        not: null
        properties: {status=class JsonSchema {
            class Schema {
                type: [string]
                format: null
                $ref: null
                description: null
                title: null
                multipleOf: null
                maximum: null
                exclusiveMaximum: null
                minimum: null
                exclusiveMinimum: null
                maxLength: null
                minLength: null
                pattern: null
                maxItems: null
                minItems: null
                uniqueItems: null
                maxProperties: null
                minProperties: null
                required: null
                not: null
                properties: null
                additionalProperties: null
                nullable: null
                readOnly: null
                writeOnly: null
                example: null
                externalDocs: null
                deprecated: null
                discriminator: null
                xml: null
                patternProperties: null
                contains: null
                $id: null
                $anchor: null
                $schema: null
                $vocabulary: null
                $dynamicAnchor: null
                $dynamicRef: null
                const: null
                contentEncoding: null
                contentMediaType: null
                contentSchema: null
                propertyNames: null
                unevaluatedProperties: null
                maxContains: null
                minContains: null
                additionalItems: null
                unevaluatedItems: null
                _if: null
                _else: null
                then: null
                dependentRequired: null
                dependentSchemas: null
                $comment: null
                prefixItems: null
                booleanSchemaValuenull
            }
        }, version=class JsonSchema {
            class Schema {
                type: [string]
                format: null
                $ref: null
                description: null
                title: null
                multipleOf: null
                maximum: null
                exclusiveMaximum: null
                minimum: null
                exclusiveMinimum: null
                maxLength: null
                minLength: null
                pattern: null
                maxItems: null
                minItems: null
                uniqueItems: null
                maxProperties: null
                minProperties: null
                required: null
                not: null
                properties: null
                additionalProperties: null
                nullable: null
                readOnly: null
                writeOnly: null
                example: null
                externalDocs: null
                deprecated: null
                discriminator: null
                xml: null
                patternProperties: null
                contains: null
                $id: null
                $anchor: null
                $schema: null
                $vocabulary: null
                $dynamicAnchor: null
                $dynamicRef: null
                const: null
                contentEncoding: null
                contentMediaType: null
                contentSchema: null
                propertyNames: null
                unevaluatedProperties: null
                maxContains: null
                minContains: null
                additionalItems: null
                unevaluatedItems: null
                _if: null
                _else: null
                then: null
                dependentRequired: null
                dependentSchemas: null
                $comment: null
                prefixItems: null
                booleanSchemaValuenull
            }
        }}
        additionalProperties: null
        nullable: null
        readOnly: null
        writeOnly: null
        example: null
        externalDocs: null
        deprecated: null
        discriminator: null
        xml: null
        patternProperties: null
        contains: null
        $id: null
        $anchor: null
        $schema: null
        $vocabulary: null
        $dynamicAnchor: null
        $dynamicRef: null
        const: null
        contentEncoding: null
        contentMediaType: null
        contentSchema: null
        propertyNames: null
        unevaluatedProperties: null
        maxContains: null
        minContains: null
        additionalItems: null
        unevaluatedItems: null
        _if: null
        _else: null
        then: null
        dependentRequired: null
        dependentSchemas: null
        $comment: null
        prefixItems: null
        booleanSchemaValuenull
    }
}}