[Bug]: Validation behavior change between openapi-generator 7.13.0 and 7.14.0 against an OpenAPI 3.1 schema with external references

[thatsdone]

Description

Validation behavior against an ISO spec (SOVD, an OpenAPI 3.1 based specification) fails after openapi-generator 7.14.0.

I was guided to report this issue here at openapi-generator repo (OpenAPITools/openapi-generator#22948) because this looks like a parser related issue.

Affected Version

version matrix of openapi-generator and swagger-parser

openapi-generator	swagger-parser	symptom
7.13.0	2.1.22	validation succeeds
7.14.0	2.1.28	validation fails
latest	2.1.37	validation fails

Steps to Reproduce

The below is a very simplified version of the SOVD (ISO 17978) API OpenAPI schema available at:
https://standards.iso.org/iso/17978/

This issue can be reproduced using below.
The original lines/files are described in-line in the below YAML.
As you can see below, the issue comes from a reference against the upstream OpenAPI schema itself.

Right now, I'm not sure if this issue belongs to the ISO SOVD OpenAPI spec. side or openapi-generator/swagger-parser side.
If it belongs to the spec. side, I can feedback to the standardization body folks.

Please save the above YAML as a file, and validate it using openapi-generator-cli 7.13.0 and 7.14.0.

Validation succeeds for 7.13.0 and fails for 7.14.0 with errors in the next section.

openapi: 3.1.0
info:
  title: simple OpenAPI schema to reproduce an issue between 7.13 and 7.14
  description: >-
    This simple.yaml is intended for reproducing issues to process the OpenAPI definition available at
    'https://standards.iso.org/iso/17978/-3/ed-1/en/ISO%2017978-3%20ed.1%20-%20openapi-specification-1.1.0-rc1.zip'
  version: 1.0.0
paths:
  /hello:
    get:
      operationId: hello
      responses:
        "200":
          description: A successful response
          $ref: '#/components/responses/Data'
components:
  responses:
    Data:
      description: Description of the response
      content:
        application/json:
          schema:
            type: object
            required:
              - items
            properties:
              items:
                message:
                  type: string
                  example: "Hello, world!"
              schema:
                $ref: "#/components/schemas/OpenApiSchema"
  schemas:
    OpenApiSchema:
      # validation fails for below (capability-description/capability-description.yaml)
      $ref: "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/refs/tags/3.1.1/schemas/v3.1/schema.yaml"
      # validation succeeds for below (commons/types.yaml)
      #$ref: "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/refs/tags/3.1.1/schemas/v3.1/schema.yaml#/$defs/schema"

Expected Behavior

Validation succeeds.

$ java -jar openapi-generator-cli-7.13.0.jar  validate -i simple.yaml
Validating spec (simple.yaml)
No validation issues detected.

Actual Behavior

Validation failed.

$ java -jar openapi-generator-cli-7.14.0.jar  validate -i simple.yaml
Validating spec (simple.yaml)
[main] ERROR i.s.v.p.reference.ReferenceVisitor - Error resolving schema #/$defs/info
java.lang.RuntimeException: Could not find /$defs/info in contents of #/$defs/info
        at io.swagger.v3.parser.reference.ReferenceVisitor.resolveSchemaRef(ReferenceVisitor.java:253)
        at io.swagger.v3.parser.reference.ReferenceVisitor.visitSchema(ReferenceVisitor.java:141)
        at io.swagger.v3.parser.reference.OpenAPI31Traverser.traverseSchema(OpenAPI31Traverser.java:801)
        at io.swagger.v3.parser.reference.OpenAPI31Traverser.traverseSchemaMap(OpenAPI31Traverser.java:960)
        at io.swagger.v3.parser.reference.OpenAPI31Traverser.traverseSchema(OpenAPI31Traverser.java:811)
        at io.swagger.v3.parser.reference.ReferenceVisitor.resolveSchemaRef(ReferenceVisitor.java:262)
        at io.swagger.v3.parser.reference.ReferenceVisitor.visitSchema(ReferenceVisitor.java:141)
        at io.swagger.v3.parser.reference.OpenAPI31Traverser.traverseSchema(OpenAPI31Traverser.java:801)
        at io.swagger.v3.parser.reference.OpenAPI31Traverser.traverseSchemaMap(OpenAPI31Traverser.java:960)
        at io.swagger.v3.parser.reference.OpenAPI31Traverser.traverseSchema(OpenAPI31Traverser.java:811)
        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.ReferenceVisitor.resolveRef(ReferenceVisitor.java:210)
        at io.swagger.v3.parser.reference.ReferenceVisitor.visitResponse(ReferenceVisitor.java:152)
        at io.swagger.v3.parser.reference.OpenAPI31Traverser.traverseResponse(OpenAPI31Traverser.java:289)
        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:227)
        at io.swagger.v3.parser.OpenAPIV3Parser.readContents(OpenAPIV3Parser.java:183)
        at io.swagger.v3.parser.OpenAPIV3Parser.readLocation(OpenAPIV3Parser.java:97)
        at io.swagger.parser.OpenAPIParser.readLocation(OpenAPIParser.java:16)
        at org.openapitools.codegen.cmd.Validate.execute(Validate.java:61)
        at org.openapitools.codegen.cmd.OpenApiGeneratorCommand.run(OpenApiGeneratorCommand.java:32)
        at org.openapitools.codegen.OpenAPIGenerator.main(OpenAPIGenerator.java:66)
(snip)

[main] WARN  o.o.codegen.utils.ModelUtils - Failed to get the schema name: #/$defs/info
[main] WARN  o.o.codegen.utils.ModelUtils - Failed to get the schema name: #/$defs/server
[main] WARN  o.o.codegen.utils.ModelUtils - Failed to get the schema name: #/$defs/paths
[main] WARN  o.o.codegen.utils.ModelUtils - Failed to get the schema name: #/$defs/path-item
[main] WARN  o.o.codegen.utils.ModelUtils - Failed to get the schema name: #/$defs/components
[main] WARN  o.o.codegen.utils.ModelUtils - Failed to get the schema name: #/$defs/security-requirement
[main] WARN  o.o.codegen.utils.ModelUtils - Failed to get the schema name: #/$defs/tag
[main] WARN  o.o.codegen.utils.ModelUtils - Failed to get the schema name: #/$defs/external-documentation
Errors:
        - Could not find /$defs/tag in contents of #/$defs/tag
        - Could not find /$defs/info in contents of #/$defs/info
        - Could not find /$defs/components in contents of #/$defs/components
        - Could not find /$defs/server in contents of #/$defs/server
        - Could not find /$defs/external-documentation in contents of #/$defs/external-documentation
        - Could not find /$defs/path-item in contents of #/$defs/path-item
        - Could not find /$defs/paths in contents of #/$defs/paths
        - Could not find /$defs/security-requirement in contents of #/$defs/security-requirement

[error] Spec has 8 errors.
$

Logs / Stack Traces

Please see above.

Environment

• Java version: OpenJDK 21
• Build tool: Maven 3.6.0
• OS: Ubuntu 24.04.1 LTS

Additional Context

Checklist

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