Clarify Breaking/Non-Breaking Changes and Improve Configuration Mechanism

[DrSatyr]

I’ve noticed that questions and issues related to how the library interprets breaking vs. non-breaking changes come up quite frequently:

https://github.com/OpenAPITools/openapi-diff/issues?q=label%3A%22Breaking%2FNon-Breaking%20classification%22

It seems like a good idea to start by documenting the library’s current behavior (e.g., in the README file). This could serve as a foundation for further discussions on what qualifies as breaking and what does not.

From what I’ve observed, it’s unlikely that a single approach will suit everyone’s needs. To address this, we might need a mechanism that allows users to configure how each rule is interpreted. Fortunately, we already have a configuration mechanism – BackwardIncompatibleProp – that can be utilized for this purpose.

I propose using this discussion to

1. document the library’s current behavior
2. identify which aspects of the behavior are perceived as breaking or non-breaking
3. explore ways to improve the configuration mechanism and the process for adding new rules.

Looking forward to your thoughts and suggestions!

[DrSatyr]

I would like to propose my vision for solving this problem:

1. Create a сonfiguration mechanism
   We need to create a configuration format that can represent all OpenAPI schema elements in the context of change types (eg breaking/non-breaking). Considering a number of rules, this mechanism should be easy to review and override.

2. Review the Current Solution
   It is necessary to review the current solution and incorporate the library's existing behavior into this configuration. At the same time, this will allow us to validate which aspects are not covered by the library.

3. Refactor the Code
   Refactor the current solution to work with the new configuration approach.

Proposed сonfiguration mechanism

Leverage CSV-Based Rule Structure
Define the rules for each element of an OpenAPI schema in a CSV format (see example below). So the library will use it as a configuration source. The default CSV rules will be shipped with the library itself. Users will be able to define a custom CSV table with overrides for default values (eg, while CLI execution with an additional parameter --rules-override=overrides.csv)

Example Table Structure

Element Path (JSON Path)	Addition	Removal	Value Change	Optional → Required	Required → Optional	Type/Range Expansion	Type/Range Restriction
$.info.title	N/A	N/A	Non-breaking	N/A	N/A	N/A	N/A
$.info.version	N/A	Breaking	Non-breaking	N/A	N/A	N/A	N/A
$.servers[*]	Non-breaking	Breaking	N/A	N/A	N/A	N/A	N/A
$.servers[*].url	N/A	N/A	Breaking	N/A	N/A	N/A	N/A
$.paths[:{path}]	Non-breaking	Breaking	N/A	N/A	N/A	N/A	N/A
$.paths[:{path}][:{method}].parameters[*].required	N/A	N/A	N/A	Breaking	Non-breaking	N/A	N/A
$.paths[:{path}][:{method}].parameters[*].schema.type	N/A	N/A	Breaking	N/A	N/A	Non-breaking	Breaking
$.paths[:{path}][:{method}].parameters[*].schema.enum	Non-breaking	Breaking	N/A	N/A	N/A	Non-breaking	Breaking
$.components.schemas[:{schema}].properties[:{prop}]	Non-breaking	Breaking	N/A	Breaking	Non-breaking	N/A	N/A
$.components.schemas[:{schema}].discriminator	Non-breaking	Breaking	Breaking	N/A	N/A	N/A	N/A
$.components.securitySchemes[:{name}].flows	Non-breaking	Breaking	N/A	N/A	N/A	N/A	N/A
$.tags[*]	Non-breaking	Non-breaking	N/A	N/A	N/A	N/A	N/A
$.externalDocs.url	Non-breaking	Non-breaking	Breaking	N/A	N/A	N/A	N/A

Please note: the data in the example can be controversial; it is just an example. I have worked with GitHub Copilot to create a table based on the OpenAPI 3.1 JSON Schema, which can serve as a starting point.

A full table is available here: https://docs.google.com/spreadsheets/d/1S_YWL1FLYBtQFL09jMZkhaKtvT0PJ9ooMzj5CANMrj4. Please feel free to request access through Google Sheets if you would like to participate or view.

This approach will make the rules clear, configurable, and extensible. I look forward to your feedback and contributions to enhance this process!