Repository navigation
False positive when adding optional property #490
Description
When comparing these 2 schemas:
test/old.json
{
"openapi": "3.0.0",
"servers": [{ "url": "https://myserver.com" }],
"info": { "title": "My API", "description": "Description", "version": "0.2.0" },
"paths": {
"/v1/entity/{id}": {
"put": {
"operationId": "myOperation",
"description": "Some description",
"requestBody": { "$ref": "#/components/requestBodies/updateBody" }
}
}
},
"components": {
"schemas": {},
"responses": {},
"requestBodies": {
"updateBody": {
"description": "Update description",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"url": { "type": "string", "description": "Some URL" }
},
"title": "updateBody",
"additionalProperties": false
}
}
}
}
},
"parameters": {}
}
}test/new.json
{
"openapi": "3.0.0",
"servers": [{ "url": "https://myserver.com" }],
"info": { "title": "My API", "description": "Description", "version": "0.2.0" },
"paths": {
"/v1/entity/{id}": {
"put": {
"operationId": "myOperation",
"description": "Some description",
"requestBody": { "$ref": "#/components/requestBodies/updateBody" }
}
}
},
"components": {
"schemas": {},
"responses": {},
"requestBodies": {
"updateBody": {
"description": "Update description",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"url": { "type": "string", "description": "Some URL" },
"url2": { "type": "string", "description": "Some URL" }
},
"title": "updateBody",
"additionalProperties": false
}
}
}
}
},
"parameters": {}
}
}I get a broken compatibility message:
docker run --rm -t -v $(pwd)/test/:/specs:ro openapitools/openapi-diff:latest --fail-on-incompatible /specs/old.json /specs/new.json
==========================================================================
== API CHANGE LOG ==
==========================================================================
My API
--------------------------------------------------------------------------
-- What's Changed --
--------------------------------------------------------------------------
- PUT /v1/entity/{id}
Request:
- Changed application/json
Schema: Broken compatibility
--------------------------------------------------------------------------
-- Result --
--------------------------------------------------------------------------
API changes broke backward compatibility
--------------------------------------------------------------------------Note that the only change is the addition of the url2 optional property:
diff -u test/old.json test/new.json
--- test/old.json 2023-03-14 17:06:02
+++ test/new.json 2023-03-14 17:06:33
@@ -22,7 +22,8 @@
"schema": {
"type": "object",
"properties": {
- "url": { "type": "string", "description": "Some URL" }
+ "url": { "type": "string", "description": "Some URL" },
+ "url2": { "type": "string", "description": "Some URL" }
},
"title": "updateBody",
"additionalProperties": falseSince the required field is absent, I would expect the addition of url2 to not create a broken compatibility error.
Activity
joschi commentedon Mar 14, 2023
I think this was originally introduced in #136 / #137.
Happy to discuss whether it still makes sense.
mas-chen commentedon Apr 4, 2023
https://www.rfc-editor.org/rfc/rfc7231#section-4.3.4
The RFC does say "SHOULD" and not "MUST" so I believe it would be good to make this strict check configurable
mas-chen commentedon Apr 4, 2023
There's similar issues here: #251 and #264