Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@ public enum BackwardIncompatibleProp {
REQUEST_PARAM_STYLE_CHANGED("incompatible.request.param.style.changed", true),
REQUEST_PARAMS_DECREASED("incompatible.request.params.decreased", true),
REQUEST_PARAMS_REQUIRED_INCREASED("incompatible.request.params.required.increased", true),
REQUEST_PROPERTIES_DECREASED("incompatible.request.properties.decreased", true),
REQUEST_READONLY_INCREASED("incompatible.request.readonly.increased", true),
REQUEST_READONLY_REQUIRED_DECREASED("incompatible.request.readonly.required.decreased", true),
REQUEST_REQUIRED_INCREASED("incompatible.request.required.increased", true),
Expand All @@ -36,6 +37,7 @@ public enum BackwardIncompatibleProp {
RESPONSE_MIN_LENGTH_INCREASED("incompatible.response.min.length.increased", false),
RESPONSE_NUMERIC_RANGE_INCREASED("incompatible.response.numeric.range.increased", false),
RESPONSE_ONEOF_INCREASED("incompatible.response.oneof.increased", true),
RESPONSE_PROPERTIES_DECREASED("incompatible.response.properties.decreased", true),
RESPONSE_REQUIRED_DECREASED("incompatible.response.required.decreased", true),
RESPONSE_RESPONSES_DECREASED("incompatible.response.responses.decreased", true),
RESPONSE_WRITEONLY_INCREASED("incompatible.response.writeonly.increased", true),
Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
package org.openapitools.openapidiff.core.model;

import static org.openapitools.openapidiff.core.model.BackwardIncompatibleProp.RESPONSE_REQUIRED_DECREASED;
import static org.openapitools.openapidiff.core.model.BackwardIncompatibleProp.REQUEST_PROPERTIES_DECREASED;
import static org.openapitools.openapidiff.core.model.BackwardIncompatibleProp.RESPONSE_PROPERTIES_DECREASED;
import static org.openapitools.openapidiff.core.model.BackwardIncompatibleProp.SCHEMA_DISCRIMINATOR_CHANGED;
import static org.openapitools.openapidiff.core.model.BackwardIncompatibleProp.SCHEMA_TYPE_CHANGED;

Expand Down Expand Up @@ -203,6 +204,11 @@ private boolean compatibleForRequest() {
// TODO: dead code? If not, create test.
return false;
}
// Removed properties are backward incompatible: existing clients may still
// send them (issue #673). Adding properties stays compatible.
if (!missingProperties.isEmpty() && REQUEST_PROPERTIES_DECREASED.enabled(context)) {
return false;
}
}
return true;
}
Expand All @@ -214,12 +220,12 @@ private boolean compatibleForResponse() {
// TODO: dead code? If not, create test.
return false;
}
if (oldSchema.getRequired() != null
&& missingProperties.keySet().stream()
.anyMatch(prop -> oldSchema.getRequired().contains(prop))) {
if (RESPONSE_REQUIRED_DECREASED.enabled(context)) {
return false;
}
// Removed properties are backward incompatible: existing clients may
// depend on receiving them (issue #673). This also covers previously
// required properties, which used to be handled here via
// RESPONSE_REQUIRED_DECREASED (still used for required -> optional).
if (!missingProperties.isEmpty() && RESPONSE_PROPERTIES_DECREASED.enabled(context)) {

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: Removing a previously required response property is still controlled by RESPONSE_REQUIRED_DECREASED through ChangedRequired, even when RESPONSE_PROPERTIES_DECREASED is disabled. Exclude removed property names from the required-decrease check so that flag applies only when the property remains and becomes optional.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At core/src/main/java/org/openapitools/openapidiff/core/model/ChangedSchema.java, line 227:

<comment>Removing a previously required response property is still controlled by `RESPONSE_REQUIRED_DECREASED` through `ChangedRequired`, even when `RESPONSE_PROPERTIES_DECREASED` is disabled. Exclude removed property names from the required-decrease check so that flag applies only when the property remains and becomes optional.</comment>

<file context>
@@ -214,12 +220,12 @@ private boolean compatibleForResponse() {
+        // depend on receiving them (issue #673). This also covers previously
+        // required properties, which used to be handled here via
+        // RESPONSE_REQUIRED_DECREASED (still used for required -> optional).
+        if (!missingProperties.isEmpty() && RESPONSE_PROPERTIES_DECREASED.enabled(context)) {
+          return false;
         }
</file context>

return false;
}
}
}
Expand Down
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
package org.openapitools.openapidiff.core;

import static io.swagger.v3.oas.models.PathItem.HttpMethod.GET;
import static io.swagger.v3.oas.models.PathItem.HttpMethod.POST;
import static org.assertj.core.api.Assertions.assertThat;
import static org.junit.jupiter.api.Assertions.assertEquals;
Expand Down Expand Up @@ -96,8 +97,11 @@ void booleanAdditionalPropertiesAreSupported() {

@Test
public void addPropertyHandlingTest() {
// Adding a property is backward compatible. Note the direction: schema 2
// has fewer properties than schema 1, so the addition goes from 2 to 1.
// Since #673, comparing 1 to 2 (a removed property) would be incompatible.
assertOpenApiBackwardCompatible(
"schemaDiff/schema-add-property-1.yaml", "schemaDiff/schema-add-property-2.yaml", true);
"schemaDiff/schema-add-property-2.yaml", "schemaDiff/schema-add-property-1.yaml", true);
}

@Test // issue #537
Expand Down Expand Up @@ -394,7 +398,8 @@ public void testAnyOfDiff() {
assertThat(changedSchema).isNotNull();
// The diff compares the *merged* schema resulting from anyOf, not the anyOf structure itself.
// See details in #772
assertThat(changedSchema.isChanged()).isEqualTo(DiffResult.COMPATIBLE);
// Since #673, removing the fieldB property makes the merged schema incompatible.
assertThat(changedSchema.isChanged()).isEqualTo(DiffResult.INCOMPATIBLE);

// fieldA only changed required status, not its schema
assertThat(changedSchema.getChangedProperties()).isEmpty();
Expand Down Expand Up @@ -422,7 +427,8 @@ public void testAllOfDiff() {
assertThat(changedSchema).isNotNull();
// The diff compares the *merged* schema resulting from allOf, not the allOf structure itself.
// See details in #772
assertThat(changedSchema.isChanged()).isEqualTo(DiffResult.COMPATIBLE);
// Since #673, removing the fieldB property makes the merged schema incompatible.
assertThat(changedSchema.isChanged()).isEqualTo(DiffResult.INCOMPATIBLE);

// fieldA only changed required status, commonField is unchanged
assertThat(changedSchema.getChangedProperties()).isEmpty();
Expand All @@ -439,6 +445,53 @@ public void testAllOfDiff() {
assertThat(changedSchema.getRequired().getIncreased()).isEmpty();
}

@Test // issue #673
public void testResponsePropertyRemovedIsIncompatible() {
ChangedOpenApi changedOpenApi =
OpenApiCompare.fromLocations(
"schemaDiff/props-removed-1.yaml", "schemaDiff/props-removed-2.yaml");
ChangedSchema changedSchema =
getResponseBodyChangedSchema(changedOpenApi, GET, "/widgets", "200", "application/json");

assertThat(changedSchema).isNotNull();
assertThat(changedSchema.getMissingProperties()).containsKey("foo");
assertThat(changedSchema.getIncreasedProperties()).isEmpty();
assertThat(changedSchema.isCoreChanged()).isEqualTo(DiffResult.INCOMPATIBLE);
assertThat(changedSchema.isChanged()).isEqualTo(DiffResult.INCOMPATIBLE);
assertThat(changedOpenApi.isChanged().isIncompatible()).isTrue();
}

@Test // issue #673
public void testResponsePropertyAddedIsCompatible() {
ChangedOpenApi changedOpenApi =
OpenApiCompare.fromLocations(
"schemaDiff/props-added-1.yaml", "schemaDiff/props-added-2.yaml");
ChangedSchema changedSchema =
getResponseBodyChangedSchema(changedOpenApi, GET, "/widgets", "200", "application/json");

assertThat(changedSchema).isNotNull();
assertThat(changedSchema.getIncreasedProperties()).containsKey("bar");
assertThat(changedSchema.getMissingProperties()).isEmpty();
assertThat(changedSchema.isCoreChanged()).isEqualTo(DiffResult.COMPATIBLE);
assertThat(changedSchema.isChanged()).isEqualTo(DiffResult.COMPATIBLE);
assertThat(changedOpenApi.isChanged().isCompatible()).isTrue();
}

@Test // issue #673
public void testResponseRequiredPropertyRemovedIsIncompatible() {
ChangedOpenApi changedOpenApi =
OpenApiCompare.fromLocations(
"schemaDiff/props-required-removed-1.yaml", "schemaDiff/props-required-removed-2.yaml");
ChangedSchema changedSchema =
getResponseBodyChangedSchema(changedOpenApi, GET, "/widgets", "200", "application/json");

assertThat(changedSchema).isNotNull();
assertThat(changedSchema.getMissingProperties()).containsKey("id");
assertThat(changedSchema.isCoreChanged()).isEqualTo(DiffResult.INCOMPATIBLE);
assertThat(changedSchema.isChanged()).isEqualTo(DiffResult.INCOMPATIBLE);
assertThat(changedOpenApi.isChanged().isIncompatible()).isTrue();
}

@Test
void renderShowsNoDifferencesWhenCSVMediaTypeResponseExampleIsByteArray() {
ChangedOpenApi changedOpenApi =
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,14 @@ public void requestPropsPutIncreased() {
assertSpecChangedButCompatible(BASE, "bc_request_schema_props_put_increased.yaml");
}

@Test
public void requestPropsDecreased() {
// Removing a property from a request schema breaks clients that still send
// it. See https://github.com/OpenAPITools/openapi-diff/issues/673
BackwardIncompatibleProp prop = REQUEST_PROPERTIES_DECREASED;
assertSpecIncompatible(BASE, "bc_request_schema_props_decreased.yaml", prop);
}

@Test
public void responseFormatDecreased() {
// TODO: Document why desired or remove support (test added to avoid unintentional regression)
Expand All @@ -56,9 +64,26 @@ public void responseFormatIncreased() {
assertOpenApiBackwardIncompatible(BASE, "bc_response_schema_format_increased.yaml");
}

@Test
public void responsePropsIncreased() {
// Adding a property to a response schema is backward compatible: existing
// clients ignore unknown fields.
assertSpecChangedButCompatible(BASE, "bc_response_schema_props_increased.yaml");
}

@Test
public void responsePropsDecreased() {
// Removing a property from a response schema breaks clients that depend on
// receiving it. See https://github.com/OpenAPITools/openapi-diff/issues/673
BackwardIncompatibleProp prop = RESPONSE_PROPERTIES_DECREASED;
assertSpecIncompatible(BASE, "bc_response_schema_props_decreased.yaml", prop);
}

@Test
public void responsePropsRequiredDecreased() {
BackwardIncompatibleProp prop = RESPONSE_REQUIRED_DECREASED;
// Removing a previously required property is covered by the general
// RESPONSE_PROPERTIES_DECREASED rule since issue #673.
BackwardIncompatibleProp prop = RESPONSE_PROPERTIES_DECREASED;
assertSpecIncompatible(BASE, "bc_response_schema_props_required_decreased.yaml", prop);
}

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -63,10 +63,10 @@ public void validateAsciiDocChangeFile() {
+ "** Media types:\n"
+ "*** Changed application/json\n"
+ "*** Schema:\n"
+ "Backward compatible\n"
+ "Broken compatibility\n"
+ "*** Missing property: childProperty (object)\n"
+ "\n"
+ "\n"
+ "NOTE: API changes are backward compatible\n");
+ "WARNING: API changes broke backward compatibility\n");
}

@Test
Expand Down
122 changes: 122 additions & 0 deletions core/src/test/resources/bc_request_schema_props_decreased.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,122 @@
openapi: 3.0.0
info:
description: myDesc
title: myTitle
version: 1.0.0
paths:
/widgets:
post:
operationId: widgetCreate
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/WidgetCreateRequest'
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/WidgetCreateResponse'
put:
operationId: widgetUpdate
requestBody:
content:
application/json:
schema:
type: object
properties:
put_prop1:
type: string
put_prop2:
type: string
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: string
components:
schemas:
WidgetCreateRequest:
type: object
properties:
to_create:
$ref: '#/components/schemas/Widget_Polymorphic'
request_prop1:
type: integer
format: int32
required:
- to_create
- request_prop1
WidgetCreateResponse:
type: object
properties:
created:
$ref: '#/components/schemas/Widget_Polymorphic'
response_prop1:
type: integer
format: int32
response_prop2:
type: integer
format: int64
required:
- created
- response_prop1
Widget_Polymorphic:
type: object
oneOf:
- $ref: '#/components/schemas/Doodad'
- $ref: '#/components/schemas/Gadget'
discriminator:
propertyName: '@type'
Widget:
type: object
properties:
'@type':
type: string
prop1:
type: string
prop2:
type: integer
format: int32
deprecated: true
stuffUnbounded:
type: object
additionalProperties:
type: string
stuffBounded:
type: object
minProperties: 1
maxProperties: 10
additionalProperties:
type: string
required:
- '@type'
- prop1
Doodad:
type: object
allOf:
- $ref: '#/components/schemas/Widget'
- type: object
properties:
doodad_prop1:
type: string
Gadget:
type: object
allOf:
- $ref: '#/components/schemas/Widget'
- type: object
properties:
gadget_prop1:
type: string
Gizmo:
type: object
allOf:
- $ref: '#/components/schemas/Widget'
- type: object
properties:
gizmo_prop1:
type: string
10 changes: 10 additions & 0 deletions core/src/test/resources/bc_request_schema_props_put_increased.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -88,6 +88,16 @@ components:
type: integer
format: int32
deprecated: true
stuffUnbounded:
type: object
additionalProperties:
type: string
stuffBounded:
type: object
minProperties: 1
maxProperties: 10
additionalProperties:
type: string
required:
- '@type'
- prop1
Expand Down
Loading