Repository navigation
Increasing the maxLength property for a String field is considered a breaking change while Decreasing it is considered as Backward compatible. #461
Description
While testing out this tool, we've noticed that increasing the maxLength property for a String field would return API changes broke backward compatibility while decreasing the maxLength property for a String field would return a API changes are backward compatible.
Shouldn’t it be the other way round? i.e.,
Increasing the maxLength property for a String field should return API changes are backward compatible and
Decreasing the maxLength property for a String field should return API changes broke backward compatibility?
If the current behaviour is the expected behaviour we would like to understand the reasoning behind it.
Here are the snippets of the json files used for the comparison in the following 2 scenarios:
Scenario -1 : Increasing the maxLength property for a String field
oldSpec.json
"SAMPLE_FIELD": {
"type": "string",
"maxLength": 2,
"nullable": true
}
newSpec.json
“SAMPLE_FIELD: {
"type": "string",
"maxLength": 5,
"nullable": true
}
Result:
-- What's Changed --
--------------------------------------------------------------------------
- GET /SAMPLETextView
Return Type:
- Changed 200 OK
Media types:
- Changed application/json
Schema: Broken compatibility
Scenario -2 : Decreasing the maxLength property for a String field
oldSpec.json
"SAMPLE_FIELD": {
"type": "string",
"maxLength": 2,
"nullable": true
}
newSpec.json
“SAMPLE”_FIELD: {
"type": "string",
"maxLength": 1,
"nullable": true
}
Result:
-- What's Changed --
--------------------------------------------------------------------------
- GET /SAMPLETextView
Return Type:
- Changed 200 OK
Media types:
- Changed application/json
Schema: Backward compatible
Thank You
Activity
[-]Increasing the maxLength property for a String field is considered a breaking change while Decreasing it's maxLength is considered as Backward compatible.[/-][+]Increasing the maxLength property for a String field is considered a breaking change while Decreasing it is considered as Backward compatible.[/+]joschi commentedon Feb 26, 2023
@Hazel-John Thanks for reporting this!
We probably have to consider whether the
minLengthandmaxLengthproperties are changed in requests or response specifications.What do you think?
edgar-philipp commentedon Mar 3, 2023
minLengthResponsedecreasejoschi commentedon Mar 4, 2023
@edgar-philipp Is this really a breaking change?
Hazel-John commentedon Mar 14, 2023
@joschi
For our use-case mentioned above, the
maxLengthproperty is changed only in theresponsespecifications.For e.g.,
SAMPLEwithmaxLengthinitially set to5.Decreasingthe maxLength to3would result in data loss, due to which we think this should be a breaking change.SAMPLEwith maxLength initially set to5.Increasingthe maxLength to6would not result in data loss, due to which we think this should be a compatible change.Kindly let us know your views on the above statement.
dhananjay12 commentedon Nov 21, 2025
Hi @joschi
Are there any plans to address/fix this in a near-future release? It would be really helpful for teams relying on openapi-diff for accurate breaking-change detection.
Thanks!
joschi commentedon Nov 21, 2025
@dhananjay12 I'm no longer involved in this project but maybe you and teams relying on openapi-diff for accurate breaking-change detection could create a pull request to address this issue. 😏
DrSatyr commentedon Nov 21, 2025
@dhananjay12, hello. There is no problem with releasing a new minor version as soon as it is fixed. So if you have a chance to provide MR for it, I would appreciate your help.
dhananjay12 commentedon Nov 21, 2025
Thanks.. I will raise a PR for it soon
fix OpenAPITools#461: add minlength breaking change detection
dhananjay12 commentedon Nov 25, 2025
Hi @DrSatyr
I created a PR for minlength logic - #863 . Please review.
maxLength handling seems to be correct. Data loss risk is a server-side concern, not a breaking-change criterion as breaking chnage should only mean whether exissiting client can call/process the new API.
fix OpenAPITools#461: add minlength breaking change detection
fix OpenAPITools#461: add minlength breaking change detection (OpenAP…