Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Treat new PUT request properties as compatible #537

Closed
westse opened this issue Jun 28, 2023 · 7 comments · Fixed by #538
Closed

Treat new PUT request properties as compatible #537

westse opened this issue Jun 28, 2023 · 7 comments · Fixed by #538
Labels
enhancement
Milestone
2.1.0

Comments

@westse
Copy link
Contributor

westse commented Jun 28, 2023

Currently new PUT request properties are treated as incompatible. This is due to #136 (with PR #137) which appear invalid in intent, implementation, and test.

  • Invalid in intent: Invalid backward compatibility result for new read-only property in PUT operations #136 claims that adding a readOnly property to the request body of a PUT request is a breaking change because clients will begin to omit it and the server will interpret the omission as a directive to delete the property. This is incorrect because the server should expect, per the OAS spec, that readOnly properties "SHOULD NOT be sent as part of the request". So it would be a bug for the server to delete any data associated with the readOnly property. Regardless, the API is left unbroken if the server simply ignores readOnly properties.
  • Invalid in implementation: the code treats as incompatible any new PUT request property, not just readOnly properties.
  • Invalid in test: no readOnly properties are tested.

In theory one could argue that some servers might enforce the "SHOULD NOT" language of the spec by returning validation errors where they didn't before, and this would constitute an API breakage. But that should be discussed in a different issue.
@mas-chen
Copy link

mas-chen commented Jul 20, 2023 •
edited
Loading

+1, or at least have this configurable since this breaks a lot of users. It has been previously reported in

#490
#264
#251

@mas-chen
Copy link

Linking your fix here: #538

@mas-chen
Copy link

@joschi do you think you could help get this fix in? Or there another workaround?

@westse
Copy link
Contributor Author

westse commented Jul 21, 2023

@mas-chen Agreed on the configurability. On this note, I'm working on a PR to enable/disable via configuration each individual backward incompatible checks. (It builds on #546 which exhaustively tests each check). Stay tuned.

westse added a commit to westse/openapi-diff that referenced this issue Jul 21, 2023
@westse
Comment referencing ticket
0821b21 
- OpenAPITools#537
@joschi joschi mentioned this issue Jul 25, 2023
Merged
joschi pushed a commit that referenced this issue Jul 25, 2023
@westse
Treat new PUT request properties as compatible again (#538)
3c026ef 
Effectively reverts change for #136 (and PR #137) which appear invalid in intent, implementation, and test.

- Invalid in intent: #136 claims that adding a readOnly property to the request body of a PUT request is a breaking change because clients will begin to omit it and the server will interpret the omission as a directive to delete the property. This is incorrect because the server should expect, [per the OAS spec](https://spec.openapis.org/oas/v3.0.3#fixed-fields-19), that readOnly properties "SHOULD NOT be sent as part of the request". So it would be a bug for the server to delete any data associated with the readOnly property. Regardless, the API is left unbroken if the server simply ignores readOnly properties.
- Invalid in implementation: the code treats as incompatible any new PUT request property, not just readOnly properties.
- Invalid in test: no readOnly properties are tested.

In theory one could argue that some servers might enforce the "SHOULD NOT" language of the spec by returning validation errors where they didn't before, and this would constitute an API breakage. But that should be discussed in a different issue.

Fixes #537
Refs #136
Refs #137
@joschi joschi added this to the 2.1.0 milestone Jul 25, 2023
@mas-chen
Copy link

Thank you @westse @joschi!

@mas-chen
Copy link

@joschi will we have a beta release soon? I'm eager to test this out!

@joschi
Copy link
Contributor

joschi commented Jul 25, 2023

@joschi will we have a beta release soon? I'm eager to test this out!

See https://github.com/OpenAPITools/openapi-diff/releases/tag/2.1.0-beta.7. Maven Central should be synced in a few minutes to hours.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
enhancement
Projects
None yet
Milestone
2.1.0
Development

Successfully merging a pull request may close this issue.

Treat new PUT request properties as compatible again westse/openapi-diff
3 participants
@joschi @mas-chen @westse