False positive when adding optional property

Open
#490 3 comments 1 reaction 0 assignees View on GitHub

Maintainers usually reply within 5 days

Nobody has claimed this yet.

Assessment

Difficulty
3/5
Estimated time
1-2 days
Newbie friendliness
42/100
Issue type
Bug
Clarity
Mostly clear
Activity status
Stale
Tech stack
java
Domain
api

Research direction

Start with the supplied test/old.json and test/new.json fixtures and reproduce the result using the Docker command in the report. Trace the request-body schema compatibility check for an added property without a required field, then add a regression test and confirm the comparison no longer reports a backward-incompatible change.

Written by the indexing model from the issue text.

Description

Breaking/Non-Breaking classification

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": false

Since the required field is absent, I would expect the addition of url2 to not create a broken compatibility error.

Dominant language
Java
Stars
1.1k
Forks
191
Avg merge
4d 23h
Merged PRs (30d)
1

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from OpenAPITools/openapi-diff

All issues in OpenAPITools/openapi-diff

Similar issues

More Java issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.