Clearly separate compatibility rules for input and output schemas. #851
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
ePaul
commented
Oct 7, 2025
| * Never change the semantic of fields (e.g. changing the semantic from | ||
| customer-number to customer-id, as both are different unique customer keys) | ||
| customer-number to customer-id, as both are different unique customer keys) | ||
| * Consider <<251>> in case a URL has to change. |
Member
Author
There was a problem hiding this comment.
ePaul
commented
Oct 8, 2025
ePaul
force-pushed
the
compatibility-separately-for-input-output
branch
from
7154a27 to
099c0c6
Compare
ePaul
added
the
major
Member
tfrauenstein
left a comment
tfrauenstein
left a comment
There was a problem hiding this comment.
Thank you for providing more clarity on compatible changes -- it is needed.
I provided some change proposals to further enhance clarity and avoid redundancies.
|
|
||
| * Add only optional, never mandatory fields. | ||
| * Never change the semantic of fields (e.g. changing the semantic from | ||
| customer-number to customer-id, as both are different unique customer keys) |
Member
There was a problem hiding this comment.
Suggested change
| customer-number to customer-id, as both are different unique customer keys) | |
| customer-number to customer-id, both being unique, but different customer keys) |
| * Never change the semantic of fields (e.g. changing the semantic from | ||
| customer-number to customer-id, as both are different unique customer keys) | ||
| customer-number to customer-id, as both are different unique customer keys) | ||
| * Consider <<251>> in case a URL has to change. |
Comment on lines
+89
to
99
| * Add only optional, never mandatory fields. | ||
| * Don't remove any fields. | ||
| * Don't make mandatory fields optional or make optional fields mandatory. | ||
| * Input fields may have (complex) constraints being validated via server-side | ||
| business logic. Never change the validation logic to be more restrictive and | ||
| make sure that all constraints are clearly defined in description. | ||
| * `enum` ranges can be reduced only if the server is ready to still accept and | ||
| handle old values. They **cannot** be extended. | ||
| * You <<112>> that are used for output parameters and likely to | ||
| be extended with growing functionality. The API definition should be updated | ||
| first before returning new values. |
Member
There was a problem hiding this comment.
Suggested change
| * Add only optional, never mandatory fields. | |
| * Don't remove any fields. | |
| * Don't make mandatory fields optional or make optional fields mandatory. | |
| * Input fields may have (complex) constraints being validated via server-side | |
| business logic. Never change the validation logic to be more restrictive and | |
| make sure that all constraints are clearly defined in description. | |
| * `enum` ranges can be reduced only if the server is ready to still accept and | |
| handle old values. They **cannot** be extended. | |
| * You <<112>> that are used for output parameters and likely to | |
| be extended with growing functionality. The API definition should be updated | |
| first before returning new values. |
Member
There was a problem hiding this comment.
This is is a consequence of the sentence before, and redundant -- should be omitted.
Member
Author
There was a problem hiding this comment.
Having the redundant information makes it easier to follow, was my idea. Though I also understand the desire to keep the rules shorter.
editorial changes: remove redundant text. Co-authored-by: Thomas Frauenstein <thomas.frauenstein@zalando.de>
editorial improvements about optional/mandatory fields Co-authored-by: Thomas Frauenstein <thomas.frauenstein@zalando.de>
editorial changes about mandatory/optional for output. Co-authored-by: Thomas Frauenstein <thomas.frauenstein@zalando.de>
remove redundand "when used for output". Co-authored-by: Thomas Frauenstein <thomas.frauenstein@zalando.de>
Co-authored-by: Thomas Frauenstein <thomas.frauenstein@zalando.de>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Triggered by a discussion in an internal chat (internal link), this makes it clearer which of the compatibility rules apply for input and output schemas, respectively.