From 80f81c7912c7e5e64be5dcf3ef367b77ba55c96f Mon Sep 17 00:00:00 2001 From: Inf1mum Date: Mon, 16 Nov 2026 16:18:01 +0300 Subject: [PATCH] Store the old/new $ref on ChangedSchema SchemaDiff resolves $ref schemas against the components before comparing them, so the fact that a schema was reached through a reference is lost in the diff result: ChangedSchema only keeps the resolved schemas. Keep the original $ref values on ChangedSchema before resolution. They are captured in SchemaDiff#computeDiffForReal, the single place where every schema pair passes through, and in the additional properties fallback of SchemaDiffResult, which builds its schema without going through that path. The refs are inert metadata for downstream consumers and do not affect change detection. Part of #956 Signed-off-by: Inf1mum --- .../openapidiff/core/compare/SchemaDiff.java | 27 +++++++++++++--- .../schemadiffresult/SchemaDiffResult.java | 4 ++- .../openapidiff/core/model/ChangedSchema.java | 31 +++++++++++++++++++ .../openapidiff/core/SchemaDiffTest.java | 29 +++++++++++++++++ .../schemaDiff/schema-ref-handling-1.yaml | 26 ++++++++++++++++ .../schemaDiff/schema-ref-handling-2.yaml | 26 ++++++++++++++++ 6 files changed, 138 insertions(+), 5 deletions(-) create mode 100644 core/src/test/resources/schemaDiff/schema-ref-handling-1.yaml create mode 100644 core/src/test/resources/schemaDiff/schema-ref-handling-2.yaml diff --git a/core/src/main/java/org/openapitools/openapidiff/core/compare/SchemaDiff.java b/core/src/main/java/org/openapitools/openapidiff/core/compare/SchemaDiff.java index fadae7a1d..1a412a702 100644 --- a/core/src/main/java/org/openapitools/openapidiff/core/compare/SchemaDiff.java +++ b/core/src/main/java/org/openapitools/openapidiff/core/compare/SchemaDiff.java @@ -340,8 +340,10 @@ protected DeferredChanged computeDeferredDiff( public DeferredChanged computeDiffForReal( RecursiveSchemaSet refSet, Schema left, Schema right, DiffContext context) { - left = refPointer.resolveRef(this.leftComponents, left, getSchemaRef(left)); - right = refPointer.resolveRef(this.rightComponents, right, getSchemaRef(right)); + String leftRef = getSchemaRef(left); + String rightRef = getSchemaRef(right); + left = refPointer.resolveRef(this.leftComponents, left, leftRef); + right = refPointer.resolveRef(this.rightComponents, right, rightRef); left = resolveComposedSchema(leftComponents, left, refSet.getLeftKeys()); right = resolveComposedSchema(rightComponents, right, refSet.getRightKeys()); @@ -352,11 +354,28 @@ public DeferredChanged computeDiffForReal( if ((left == null || right == null) || !Objects.equals(left.getType(), right.getType()) || !Objects.equals(left.getFormat(), right.getFormat())) { - return getTypeChangedSchema(left, right, context); + return keepSourceRefs(getTypeChangedSchema(left, right, context), leftRef, rightRef); } // If schema type is same then get specific SchemaDiffResult and compare the properties SchemaDiffResult result = SchemaDiff.getSchemaDiffResult(right.getClass(), openApiDiff); - return result.diff(refSet, leftComponents, rightComponents, left, right, context); + return keepSourceRefs( + result.diff(refSet, leftComponents, rightComponents, left, right, context), + leftRef, + rightRef); + } + + /** + * Keeps the `$ref` values the schemas were referenced by on the resulting {@link ChangedSchema}; + * reference resolution drops them, and downstream consumers need to know which component schemas + * were compared. + */ + private static DeferredChanged keepSourceRefs( + DeferredChanged diff, String oldRef, String newRef) { + return diff.mapOptional( + changedSchema -> { + changedSchema.ifPresent(schema -> schema.setOldRef(oldRef).setNewRef(newRef)); + return changedSchema; + }); } } diff --git a/core/src/main/java/org/openapitools/openapidiff/core/compare/schemadiffresult/SchemaDiffResult.java b/core/src/main/java/org/openapitools/openapidiff/core/compare/schemadiffresult/SchemaDiffResult.java index 67d976a33..ac0c4ea8b 100644 --- a/core/src/main/java/org/openapitools/openapidiff/core/compare/schemadiffresult/SchemaDiffResult.java +++ b/core/src/main/java/org/openapitools/openapidiff/core/compare/schemadiffresult/SchemaDiffResult.java @@ -182,7 +182,9 @@ private void compareAdditionalProperties( new ChangedSchema() .setContext(context) .setOldSchema(leftAdditionalSchema) - .setNewSchema(rightAdditionalSchema); + .setNewSchema(rightAdditionalSchema) + .setOldRef(ofNullable(leftAdditionalSchema).map(Schema::get$ref).orElse(null)) + .setNewRef(ofNullable(rightAdditionalSchema).map(Schema::get$ref).orElse(null)); if (left != null && right != null) { DeferredChanged addPropChangedSchemaOP = openApiDiff diff --git a/core/src/main/java/org/openapitools/openapidiff/core/model/ChangedSchema.java b/core/src/main/java/org/openapitools/openapidiff/core/model/ChangedSchema.java index 30d126fba..2d3e5d56c 100644 --- a/core/src/main/java/org/openapitools/openapidiff/core/model/ChangedSchema.java +++ b/core/src/main/java/org/openapitools/openapidiff/core/model/ChangedSchema.java @@ -33,6 +33,11 @@ public class ChangedSchema implements ComposedChanged { protected DiffContext context; protected Schema oldSchema; protected Schema newSchema; + // The `$ref` values the old/new schemas were referenced by before the diff resolved them; null + // when the schema was inline. Metadata for downstream consumers only; it does not affect + // change detection. + protected String oldRef; + protected String newRef; protected String type; protected Map changedProperties; protected Map> increasedProperties; @@ -238,6 +243,14 @@ public Schema getNewSchema() { return this.newSchema; } + public String getOldRef() { + return this.oldRef; + } + + public String getNewRef() { + return this.newRef; + } + public String getType() { return this.type; } @@ -381,6 +394,16 @@ public ChangedSchema setNewSchema(final Schema newSchema) { return this; } + public ChangedSchema setOldRef(final String oldRef) { + this.oldRef = oldRef; + return this; + } + + public ChangedSchema setNewRef(final String newRef) { + this.newRef = newRef; + return this; + } + public ChangedSchema setType(final String type) { this.type = type; return this; @@ -586,6 +609,8 @@ public boolean equals(Object o) { && Objects.equals(context, that.context) && Objects.equals(oldSchema, that.oldSchema) && Objects.equals(newSchema, that.newSchema) + && Objects.equals(oldRef, that.oldRef) + && Objects.equals(newRef, that.newRef) && Objects.equals(type, that.type) && Objects.equals(changedProperties, that.changedProperties) && Objects.equals(increasedProperties, that.increasedProperties) @@ -620,6 +645,8 @@ public int hashCode() { context, oldSchema, newSchema, + oldRef, + newRef, type, changedProperties, increasedProperties, @@ -662,6 +689,10 @@ public java.lang.String toString() { + this.getOldSchema() + ", newSchema=" + this.getNewSchema() + + ", oldRef=" + + this.getOldRef() + + ", newRef=" + + this.getNewRef() + ", type=" + this.getType() + ", changedProperties=" diff --git a/core/src/test/java/org/openapitools/openapidiff/core/SchemaDiffTest.java b/core/src/test/java/org/openapitools/openapidiff/core/SchemaDiffTest.java index b5cdae032..902c5d21c 100644 --- a/core/src/test/java/org/openapitools/openapidiff/core/SchemaDiffTest.java +++ b/core/src/test/java/org/openapitools/openapidiff/core/SchemaDiffTest.java @@ -4,6 +4,7 @@ import static org.assertj.core.api.Assertions.assertThat; import static org.junit.jupiter.api.Assertions.assertEquals; import static org.junit.jupiter.api.Assertions.assertNotNull; +import static org.junit.jupiter.api.Assertions.assertNull; import static org.junit.jupiter.api.Assertions.assertTrue; import static org.openapitools.openapidiff.core.ChangesResolver.getRequestBodyChangedSchema; import static org.openapitools.openapidiff.core.ChangesResolver.getResponseBodyChangedSchema; @@ -52,6 +53,34 @@ public void schemaPropertyTypeChanged() { assertTrue(changedSchema.getChangedProperties().get("field1").isChangedType()); } + @Test // issue #956 + public void schemaRefsAreKeptOnChangedSchema() { + ChangedOpenApi changedOpenApi = + OpenApiCompare.fromLocations( + "schemaDiff/schema-ref-handling-1.yaml", "schemaDiff/schema-ref-handling-2.yaml"); + + ChangedSchema requestBodySchema = + getRequestBodyChangedSchema(changedOpenApi, POST, "/widgets", "application/json"); + assertNotNull(requestBodySchema); + // The request body schema is a reference to a component schema on both sides + assertEquals("#/components/schemas/Widget", requestBodySchema.getOldRef()); + assertEquals("#/components/schemas/Widget", requestBodySchema.getNewRef()); + + // A property that is itself a reference keeps the refs it was reached through + ChangedSchema weight = requestBodySchema.getChangedProperties().get("weight"); + assertNotNull(weight); + assertTrue(weight.isChangedType()); + assertEquals("#/components/schemas/Weight", weight.getOldRef()); + assertEquals("#/components/schemas/Weight", weight.getNewRef()); + + // An inline property has no refs to keep + ChangedSchema label = requestBodySchema.getChangedProperties().get("label"); + assertNotNull(label); + assertTrue(label.isChangedType()); + assertNull(label.getOldRef()); + assertNull(label.getNewRef()); + } + @Test // issue #485 public void schemaBecomesDeprecatedTest() { ChangedOpenApi changedOpenApi = diff --git a/core/src/test/resources/schemaDiff/schema-ref-handling-1.yaml b/core/src/test/resources/schemaDiff/schema-ref-handling-1.yaml new file mode 100644 index 000000000..b043bad21 --- /dev/null +++ b/core/src/test/resources/schemaDiff/schema-ref-handling-1.yaml @@ -0,0 +1,26 @@ +openapi: 3.0.0 +info: + title: Schema Ref Handling Test - Before + version: 1.0.0 +paths: + /widgets: + post: + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Widget' + responses: + '200': + description: OK +components: + schemas: + Widget: + type: object + properties: + weight: + $ref: '#/components/schemas/Weight' + label: + type: string + Weight: + type: integer diff --git a/core/src/test/resources/schemaDiff/schema-ref-handling-2.yaml b/core/src/test/resources/schemaDiff/schema-ref-handling-2.yaml new file mode 100644 index 000000000..640d45e64 --- /dev/null +++ b/core/src/test/resources/schemaDiff/schema-ref-handling-2.yaml @@ -0,0 +1,26 @@ +openapi: 3.0.0 +info: + title: Schema Ref Handling Test - After + version: 1.0.0 +paths: + /widgets: + post: + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Widget' + responses: + '200': + description: OK +components: + schemas: + Widget: + type: object + properties: + weight: + $ref: '#/components/schemas/Weight' + label: + type: integer # Changed from string to integer + Weight: + type: string # Changed from integer to string