Repository navigation
Conversation
What: - removing a property from a request or response schema is now reported as backward incompatible, gated by two new config flags enabled by default: incompatible.request.properties.decreased (REQUEST_PROPERTIES_DECREASED) and incompatible.response.properties.decreased (RESPONSE_PROPERTIES_DECREASED) - adding properties stays backward compatible - removal of a previously required response property is now governed by RESPONSE_PROPERTIES_DECREASED; RESPONSE_REQUIRED_DECREASED continues to cover required -> optional changes (property still present) Why: - previously only removing a required property from a response schema was incompatible; removing an optional property (or any property in a request context) was reported as compatible, so clients depending on the deleted property went unnoticed. Renames surface as the missing old property, since no rename heuristic is attempted (Fixes OpenAPITools#673, addresses OpenAPITools#611) How: - ChangedSchema.compatibleForRequest/compatibleForResponse now check missingProperties through the new BackwardIncompatibleProp entries, mirroring the directional pattern used by ChangedEnum and ChangedOneOfSchema; readOnly properties in requests and writeOnly properties in responses are already filtered out of missingProperties, so they remain unflagged - SchemaBCTest gains flag tests for request/response property removal, SchemaDiffTest gains model tests (removed -> incompatible, added -> compatible, required removed -> incompatible), fixtures that incidentally removed properties were cleaned up, and the expected AsciidocRenderTest output for a removed property now shows the incompatible verdict Signed-off-by: Inf1mum <vadimlazuk5@gmail.com>
There was a problem hiding this comment.
1 issue found across 19 files
Reply with feedback, questions, or to request a fix.
View guided diff | Re-trigger cubic
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. 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. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="core/src/main/java/org/openapitools/openapidiff/core/model/ChangedSchema.java">
<violation number="1" location="core/src/main/java/org/openapitools/openapidiff/core/model/ChangedSchema.java:227">
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.</violation>
</file>
Removing a previously required response property was still reported as incompatible through RESPONSE_REQUIRED_DECREASED via ChangedRequired, even when RESPONSE_PROPERTIES_DECREASED was disabled. Required entries whose property no longer exists are now excluded when building ChangedRequired, so RESPONSE_REQUIRED_DECREASED only covers required -> optional changes on properties that still exist and property removal is governed solely by RESPONSE_PROPERTIES_DECREASED, as described in the PR. Signed-off-by: Inf1mum <vadimlazuk5@gmail.com>
There was a problem hiding this comment.
1 issue found across 4 files (changes from recent commits).
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. 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. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="core/src/main/java/org/openapitools/openapidiff/core/compare/schemadiffresult/SchemaDiffResult.java">
<violation number="1" location="core/src/main/java/org/openapitools/openapidiff/core/compare/schemadiffresult/SchemaDiffResult.java:174">
P2: Removing a property that is still listed in `required` makes this helper drop that name from the old required list, so `ListDiff` reports it as a required increase. In request context this yields `REQUEST_REQUIRED_INCREASED` even though the required set is unchanged and `REQUEST_PROPERTIES_DECREASED` is disabled. Keep names that are still present in `right.getRequired()` in the old list.</violation>
</file>
Reply with feedback, questions, or to request a fix.
View guided diff | Re-trigger cubic
| Set<String> newProperties = | ||
| right.getProperties() == null ? new LinkedHashSet<>() : right.getProperties().keySet(); | ||
| List<String> result = new ArrayList<>(); | ||
| for (String name : left.getRequired()) { |
There was a problem hiding this comment.
P2: Removing a property that is still listed in required makes this helper drop that name from the old required list, so ListDiff reports it as a required increase. In request context this yields REQUEST_REQUIRED_INCREASED even though the required set is unchanged and REQUEST_PROPERTIES_DECREASED is disabled. Keep names that are still present in right.getRequired() in the old list.
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/compare/schemadiffresult/SchemaDiffResult.java, line 174:
<comment>Removing a property that is still listed in `required` makes this helper drop that name from the old required list, so `ListDiff` reports it as a required increase. In request context this yields `REQUEST_REQUIRED_INCREASED` even though the required set is unchanged and `REQUEST_PROPERTIES_DECREASED` is disabled. Keep names that are still present in `right.getRequired()` in the old list.</comment>
<file context>
@@ -158,6 +162,23 @@ private Map<String, Schema<?>> filterProperties(
+ Set<String> newProperties =
+ right.getProperties() == null ? new LinkedHashSet<>() : right.getProperties().keySet();
+ List<String> result = new ArrayList<>();
+ for (String name : left.getRequired()) {
+ if (newProperties.contains(name) || !oldProperties.contains(name)) {
+ result.add(name);
</file context>
|
Valid — ChangedRequired was built from the raw required lists, so a fully removed property still landed in getMissing() and kept reporting incompatible via RESPONSE_REQUIRED_DECREASED even with RESPONSE_PROPERTIES_DECREASED disabled. Fixed by excluding required entries whose property no longer exists when building ChangedRequired: RESPONSE_REQUIRED_DECREASED now covers only required→optional on surviving properties, and property removal is governed solely by RESPONSE_PROPERTIES_DECREASED. Covered by SchemaBCTest#responsePropsRequiredRemoved and SchemaDiffTest#testRemovedRequiredPropertyNotReportedAsRequiredDecrease; full core suite green. |
What
Removing a property from a request or response schema is now reported as backward incompatible. Adding properties remains backward compatible.
The verdict is gated by two new config flags (both enabled by default), so it can be tuned per direction like the other schema rules:
incompatible.request.properties.decreased(REQUEST_PROPERTIES_DECREASED)incompatible.response.properties.decreased(RESPONSE_PROPERTIES_DECREASED)Removal of a previously required response property is now governed by
RESPONSE_PROPERTIES_DECREASED.RESPONSE_REQUIRED_DECREASEDis unchanged where it is still meaningful: a property that keeps existing but moves from required to optional in a response.Why
Previously only removing a required property from a response schema was incompatible. Removing an optional property - or any property from a request schema - was reported as backward compatible, so clients depending on the deleted property went unnoticed.
For renames, no rename heuristic is attempted (too risky to guess intent); a renamed property surfaces as the missing old property, which is now incompatible, so a rename is no longer silently reported as backward compatible.
Fixes #673, and addresses the schema-property part of #611 (metadata/description changes being reported as compatible is a separate topic). Related context: #724 discusses configurable compatibility rules, #264/#490 already confirmed that adding optional properties must stay compatible (kept as is), and #940 applied the same directional gating pattern to request-body requiredness.
How
ChangedSchema.compatibleForRequest()/compatibleForResponse()now checkmissingPropertiesthrough the newBackwardIncompatiblePropentries, mirroring the directional pattern already used byChangedEnum(REQUEST_ENUM_DECREASED) andChangedOneOfSchema(REQUEST_ONEOF_DECREASED/RESPONSE_ONEOF_INCREASED).Notes on scope:
readOnlyin a request context orwriteOnlyin a response context were already filtered out ofmissingPropertiesbySchemaDiffResult.filterProperties, so they remain unflagged.ComposedSchemaDiffResult, so that path is unaffected.Tests:
SchemaBCTest: flag tests for request property removal, response property removal, response required-property removal, plus response property addition (compatible).SchemaDiffTest: model tests - property removed -> incompatible, property added -> compatible, required property removed -> incompatible.testAnyOfDiff/testAllOfDiffnow expect incompatible because their fixtures remove a property, andaddPropertyHandlingTestcompares the pair in the direction that actually adds the property (its fixtures date back to the module split; 1 -> 2 was a removal).bc_schema_pattern_changed,bc_schema_type_changed,bc_request_schema_props_put_increased,bc_response_schema_props_required_decreased,bc_schema_changed_but_compatible) incidentally dropped optional properties fromWidget; those incidental removals are now incompatible, so the fixtures were cleaned up to keep testing only what they meant to test.AsciidocRenderTest.validateAsciiDocChangeFileasserts the exact render output for a removed-property spec; the expected output now showsBroken compatibility, the missing property line, and the WARNING footer.CLI check on a minimal spec pair (GET/POST returning a schema with
foo):foo:Schema: Broken compatibility,Missing property: foo (string), exit code 1 with--fail-on-incompatible(wasBackward compatible, exit 0)foo->bar: reported viaMissing property: foo, exit 1bar:API changes are backward compatible, exit 0falsevia--config-file: back toBackward compatible, exit 0Summary by cubic
Removing a property from a request or response schema is now reported as backward incompatible, so clients that depend on the deleted property no longer go unnoticed. Previously only removing a required response property was flagged; removing optional properties or any request property was reported as compatible.
Adding properties stays compatible, and no rename heuristic is attempted, so renames surface as missing properties.
REQUEST_PROPERTIES_DECREASEDandRESPONSE_PROPERTIES_DECREASEDgate the verdict per direction, both enabled by default.RESPONSE_REQUIRED_DECREASEDnow only covers properties that remain but move from required to optional; removed required properties are excluded from the required diff so they don't trip that rule.Fixes #673 and addresses the schema-property part of #611.
Written for commit fd4f808. Summary will update on new commits.