Skip to content

Property type change on referenced component schema is silently ignored #910

Description

@gorazdio

Library version: org.openapitools.openapidiff:openapi-diff-core:2.1.7
Java: 21
OpenAPI version of test specs: 3.1.0 (also reproduces on 3.0.x)

Summary

When the only difference between two specs is a type change on a property of a referenced component schema, OpenApiCompare.fromContents reports zero changes. Both getChangedOperations() and getChangedSchemas() are empty. Other property-level changes (required list deltas, enum value deltas) on the same referenced schema are detected normally — only type swaps are dropped.

Minimal reproduction

old.yaml:

openapi: 3.1.0
info:
  title: t
  version: '1'
paths:
  /widgets:
    get:
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Widget'
components:
  schemas:
    Widget:
      type: object
      properties:
        weight:
          type: integer

new.yaml — identical except for weight.type:

openapi: 3.1.0
info:
  title: t
  version: '1'
paths:
  /widgets:
    get:
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Widget'
components:
  schemas:
    Widget:
      type: object
      properties:
        weight:
          type: string
import org.openapitools.openapidiff.core.OpenApiCompare;
import org.openapitools.openapidiff.core.model.ChangedOpenApi;
import java.nio.file.*;

public class Repro {
    public static void main(String[] a) throws Exception {
        String prev = Files.readString(Path.of("old.yaml"));
        String curr = Files.readString(Path.of("new.yaml"));
        ChangedOpenApi d = OpenApiCompare.fromContents(prev, curr);
        System.out.println("missingEndpoints: " + d.getMissingEndpoints().size());
        System.out.println("newEndpoints:     " + d.getNewEndpoints().size());
        System.out.println("changedOperations:" + d.getChangedOperations().size());
        System.out.println("changedSchemas:   " + d.getChangedSchemas().size());
    }
}

Actual output

missingEndpoints: 0
newEndpoints:     0
changedOperations:0
changedSchemas:   0

Expected output

A non-empty changedOperations (or changedSchemas) containing an INCOMPATIBLE entry for the property weight on Widget.

Other findings

  • Reproduces with OpenAPIParser + ParseOptions.setResolveFully(true) and OpenApiCompare.fromSpecifications(...).
  • Inverting the spec versions (3.1.0 ↔ 3.0.3) does not change the result.
  • The same fixture with a required: list change instead (e.g. adding weight to required) is detected correctly — changedOperations and changedSchemas are populated. So the parser does diff the referenced schema; only the type field is being skipped.
  • As a workaround, walking the resolved Schema tree manually after setResolveFully(true) and comparing Schema.getType() / Schema.getTypes() recovers the change.

Happy to put up a PR if pointers to where the schema-type comparator lives would help.

Activity

  1. DrSatyr commented on Jul 8, 2026

    @DrSatyr
    Collaborator

    Thanks for the report. I checked the same scenario against the currently supported OpenAPI 3.0.x path.

    For OpenAPI 3.0.x, a type change on a property of a referenced component schema is detected correctly. There is already coverage for this class of change here:

    https://github.com/OpenAPITools/openapi-diff/blob/master/core/src/test/java/org/openapitools/openapidiff/core/SchemaDiffTest.java#L40-L53

    Fixtures:
    https://github.com/OpenAPITools/openapi-diff/blob/master/core/src/test/resources/schemaDiff/schema-props-type-handling-1.yaml#L1-L23
    https://github.com/OpenAPITools/openapi-diff/blob/master/core/src/test/resources/schemaDiff/schema-props-type-handling-2.yaml#L1-L23

    I also verified the exact shape from this issue locally, but with openapi: 3.0.3 instead of 3.1.0: GET /widgets, 200 response, application/json, $ref to #/components/schemas/Widget, and Widget.properties.weight.type changed from integer to string. That test passes and reports one changed operation and one changed schema.

    The same local test fails when only the OpenAPI version is changed to 3.1.0, matching the behavior described in this issue.

    So this does not appear to be a general bug in referenced component schema comparison for OpenAPI 3.0.x. It looks specific to OpenAPI 3.1 handling. OpenAPI 3.1 support has been tracked separately, #777

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions