Breaking-changes in Requests vs. Responses

As users of oasdiff, you may have noticed the heavy lifting that is currently on-going with regards to the changelog, many new checks have recently been introduced and many more are in progress.

In one of the recent pull requests, we encountered an interesting question.

The PR added a changelog message for the case of adding a schema under “oneOf":

The question we encountered is whether this is a breaking change? Or, in other words, could this change break a client that is sending or receiving some data on the affected endpoint?


To answer this, we first define the flow in question: is it a request or a response?

In this case, it’s a response (oasdiff treats changes in requests separately from responses).

 

Luckily, we already had a point of a reference: when removing a schema from “oneOf", in requests, oasdiff classifies the change as BREAKING.

 

My intuition was that these two changes are mirrors of each-other, and, as such, should be classified alike. Either both are BREAKING or both are NON-BREAKING.


Why is removing a schema from “oneOf" in request breaking?

Because a client may have been sending data that matches that specific schema and after removal, the server will not accept this kind of data anymore.

 

And why is adding a schema to “oneOf" in response breaking?

Because the client may have not been expecting this kind of data in response and will start receiving this response after the change.

 

To generalize, here’s a geometrical representation of the question: does every breaking change has a twin with opposite flow (request vs response) and opposite operation (adding vs removing)?

At this point, I would like to ask you for your opinion, are breaking-changes in responses a mirror of breaking-changes in requests or do you think otherwise?

And specifically, should adding a schema under “oneOf" in response be classified as BREAKING or not?

Please join the discussion on GitHub.