From 2a7e5b51528d0314469ab2ff7af9251268f66365 Mon Sep 17 00:00:00 2001 From: Thomas Frauenstein Date: Fri, 26 Apr 2024 17:16:29 +0200 Subject: [PATCH 1/9] Update compatibility.adoc --- chapters/compatibility.adoc | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/chapters/compatibility.adoc b/chapters/compatibility.adoc index dc52c1af..40477f61 100644 --- a/chapters/compatibility.adoc +++ b/chapters/compatibility.adoc @@ -55,9 +55,10 @@ services in a backward-compatible way: * Enum ranges cannot be extended when used for output parameters — clients may not be prepared to handle it. However, enum ranges can be extended when used for input parameters. -* Use {x-extensible-enum}, if range is used for output parameters and likely to +* Use {x-extensible-enum} (see <<112, rule 112>>), if range is used for output parameters and likely to be extended with growing functionality. It defines an open list of explicit - values and clients must be agnostic to new values. + values and clients must be agnostic or provide default behavior for unknown + values (see <<108, rule 118>>). * Consider <<250>> in case a URL has to change. @@ -124,7 +125,7 @@ Service clients should apply the robustness principle: http://martinfowler.com/bliki/TolerantReader.html["TolerantReader"] post), i.e. ignore new fields but do not eliminate them from payload if needed for subsequent {PUT} requests. -** Be prepared that {x-extensible-enum} return parameter may deliver new values; +** Be prepared that {x-extensible-enum} return parameters (see <<112, rule 112>>) may deliver new values; either be agnostic or provide default behavior for unknown values. ** Be prepared to handle HTTP status codes not explicitly specified in endpoint definitions. Note also, that status codes are extensible. Default handling is From 7ee0fe18cc7ba16aa7625af7dc57608728056613 Mon Sep 17 00:00:00 2001 From: Thomas Frauenstein Date: Fri, 26 Apr 2024 17:26:41 +0200 Subject: [PATCH 2/9] Update events.adoc --- chapters/events.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/chapters/events.adoc b/chapters/events.adoc index b05b2c02..ddfe8d84 100644 --- a/chapters/events.adoc +++ b/chapters/events.adoc @@ -960,6 +960,7 @@ seen by consumers - * Changing the order of values with same type in an array. * Removing optional fields. * Removing an individual value from an enumeration. +* Adding new value to a `x-extensible-enum` field (see <<112, rule 112>> and <<108, rule 108>>). These are considered backwards-incompatible changes, as seen by consumers - @@ -971,5 +972,4 @@ consumers - known as a tuple). * Adding a new optional field to redefine the meaning of an existing field (also known as a co-occurrence constraint). -* Adding a value to an enumeration (note that <<112,`x-extensible-enum`>> -is not available in JSON Schema) +* Adding a value to an enumeration. Instead, you <<112>>. From 58871e6c914f4e7e1fa834932b72579348b00b13 Mon Sep 17 00:00:00 2001 From: Thomas Frauenstein Date: Fri, 26 Apr 2024 17:27:58 +0200 Subject: [PATCH 3/9] Update compatibility.adoc --- chapters/compatibility.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/chapters/compatibility.adoc b/chapters/compatibility.adoc index 40477f61..510aa242 100644 --- a/chapters/compatibility.adoc +++ b/chapters/compatibility.adoc @@ -290,7 +290,7 @@ level data structures, since they don't support compatible, future extensions. [#112] -== {SHOULD} used open-ended list of values (`x-extensible-enum`) for enumerations +== {SHOULD} use open-ended list of values (`x-extensible-enum`) for enumerations Enumerations are per definition closed sets of values that are assumed to be complete and not intended for extension. This closed principle of enumerations From a3313deb2b965671422173b69f5843f595050148 Mon Sep 17 00:00:00 2001 From: Thomas Frauenstein Date: Mon, 29 Apr 2024 16:50:55 +0200 Subject: [PATCH 4/9] Update chapters/compatibility.adoc Co-authored-by: a1exsh --- chapters/compatibility.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/chapters/compatibility.adoc b/chapters/compatibility.adoc index 510aa242..9fc54bf4 100644 --- a/chapters/compatibility.adoc +++ b/chapters/compatibility.adoc @@ -58,7 +58,7 @@ services in a backward-compatible way: * Use {x-extensible-enum} (see <<112, rule 112>>), if range is used for output parameters and likely to be extended with growing functionality. It defines an open list of explicit values and clients must be agnostic or provide default behavior for unknown - values (see <<108, rule 118>>). + values (see <<108, rule 108>>). * Consider <<250>> in case a URL has to change. From 57d92446f848636fc2ac465a3ed844b351a7ea93 Mon Sep 17 00:00:00 2001 From: Thomas Frauenstein Date: Tue, 25 Jun 2024 11:38:17 +0200 Subject: [PATCH 5/9] Update according to API Guild discussion As discussed in the API Guild meeting ([internal link](https://docs.google.com/document/d/1NahSuMC0LRwFTTrln2m0iDLq0nHzGmF59Gv7xBhKPfQ/edit#bookmark=id.h23t4po7q2os)) --- chapters/compatibility.adoc | 37 +++++++++++++++++++++---------------- 1 file changed, 21 insertions(+), 16 deletions(-) diff --git a/chapters/compatibility.adoc b/chapters/compatibility.adoc index 9fc54bf4..6f489e1e 100644 --- a/chapters/compatibility.adoc +++ b/chapters/compatibility.adoc @@ -49,16 +49,15 @@ services in a backward-compatible way: * 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 when used as input parameters, only if the server - is ready to accept and handle old range values too. Enum range can be reduced +* `enum` ranges can be reduced when used as input parameters, only if the server + is ready to accept and handle old range values too. The range can be reduced when used as output parameters. -* Enum ranges cannot be extended when used for output parameters — clients may +* `enum` ranges cannot be extended when used for output parameters — clients may not be prepared to handle it. However, enum ranges can be extended when used for input parameters. -* Use {x-extensible-enum} (see <<112, rule 112>>), if range is used for output parameters and likely to - be extended with growing functionality. It defines an open list of explicit - values and clients must be agnostic or provide default behavior for unknown - values (see <<108, rule 108>>). +* 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. * Consider <<250>> in case a URL has to change. @@ -126,7 +125,7 @@ Service clients should apply the robustness principle: i.e. ignore new fields but do not eliminate them from payload if needed for subsequent {PUT} requests. ** Be prepared that {x-extensible-enum} return parameters (see <<112, rule 112>>) may deliver new values; - either be agnostic or provide default behavior for unknown values. + either be agnostic or provide default behavior for unknown values, and do not eliminate them. ** Be prepared to handle HTTP status codes not explicitly specified in endpoint definitions. Note also, that status codes are extensible. Default handling is how you would treat the corresponding {x00} code (see @@ -290,12 +289,12 @@ level data structures, since they don't support compatible, future extensions. [#112] -== {SHOULD} use open-ended list of values (`x-extensible-enum`) for enumerations +== {SHOULD} use open-ended list of values (`x-extensible-enum`) for enumeration types -Enumerations are per definition closed sets of values that are assumed to be +JSON schema `enum` is per definition a closed set of values that is assumed to be complete and not intended for extension. This closed principle of enumerations imposes compatibility issues when an enumeration must be extended. To avoid -these issues, we strongly recommend to use an open-ended list of values instead +these issues, we recommend to use an open-ended list of values instead of an enumeration unless: 1. the API has full control of the enumeration values, i.e. the list of values @@ -303,8 +302,7 @@ of an enumeration unless: 2. the list of values is complete with respect to any thinkable and unthinkable future feature. -To specify an open-ended list of values use the marker {x-extensible-enum} as -follows: +To specify an open-ended list of values via the {x-extensible-enum} property as follows: [source,yaml] ---- @@ -316,14 +314,21 @@ delivery_methods: - EMAIL ---- -*Note:* {x-extensible-enum} is not JSON Schema conform but will be ignored by -most tools. +*Note:* {x-extensible-enum} is a proprietary extension of the JSON Schema standard that +will be ignored by most tools. See <<240>> about enum value naming conventions. +Note, {x-extensible-enum} is a different concept than JSON schema `examples` which is +just a list of few example values, whereas {x-extensible-enum} defines all valid +values (for a specific API and service version) and has the advantage of an extensible +full type-range specification that is validated by the service. + *Important:* Clients must be prepared for extensions of enums returned with server responses, i.e. must implement a fallback / default behavior to handle unknown new enum values -- see <<108>>. API owners must take care to extend enums in a compatible way that does not change the semantics of already existing enum values, for instance, do not split an old enum value -into two new enum values. +into two new enum values. Services should only extend {x-extensible-enum} ranges, and only accept +and return values listed in the latest API version which needs to be updated first before +providing new values -- see also <<107>>. From c78c48957279f4bc28b2f3fab6d8a552890b8df8 Mon Sep 17 00:00:00 2001 From: Thomas Frauenstein Date: Tue, 25 Jun 2024 18:46:48 +0200 Subject: [PATCH 6/9] Update events.adoc --- chapters/events.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/chapters/events.adoc b/chapters/events.adoc index ddfe8d84..477b45b2 100644 --- a/chapters/events.adoc +++ b/chapters/events.adoc @@ -960,7 +960,7 @@ seen by consumers - * Changing the order of values with same type in an array. * Removing optional fields. * Removing an individual value from an enumeration. -* Adding new value to a `x-extensible-enum` field (see <<112, rule 112>> and <<108, rule 108>>). +* Adding new value to a {x-extensible-enum} field (see <<112, rule 112>> and <<108, rule 108>>). These are considered backwards-incompatible changes, as seen by consumers - From 523709281c22469d48887c1b0e9ac9f9c530313b Mon Sep 17 00:00:00 2001 From: Thomas Frauenstein Date: Tue, 25 Jun 2024 19:40:23 +0200 Subject: [PATCH 7/9] Update compatibility.adoc --- chapters/compatibility.adoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/chapters/compatibility.adoc b/chapters/compatibility.adoc index 6f489e1e..3b39bb8f 100644 --- a/chapters/compatibility.adoc +++ b/chapters/compatibility.adoc @@ -315,7 +315,7 @@ delivery_methods: ---- *Note:* {x-extensible-enum} is a proprietary extension of the JSON Schema standard that -will be ignored by most tools. +is e.g. visible via Swagger UI and ignored by most tools. See <<240>> about enum value naming conventions. @@ -329,6 +329,6 @@ must implement a fallback / default behavior to handle unknown new enum values - API owners must take care to extend enums in a compatible way that does not change the semantics of already existing enum values, for instance, do not split an old enum value into two new enum values. Services should only extend {x-extensible-enum} ranges, and only accept -and return values listed in the latest API version which needs to be updated first before -providing new values -- see also <<107>>. +and return values listed in the API definition, i.e. the API definition needs to be updated first +before the service accepts/returns new values -- see also <<107>>. From 2134840559f0b60abe6c65d046af3ab943ce9479 Mon Sep 17 00:00:00 2001 From: Thomas Frauenstein Date: Thu, 27 Jun 2024 18:05:39 +0200 Subject: [PATCH 8/9] Update chapters/compatibility.adoc Co-authored-by: Tronje Krop --- chapters/compatibility.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/chapters/compatibility.adoc b/chapters/compatibility.adoc index 3b39bb8f..86724a0c 100644 --- a/chapters/compatibility.adoc +++ b/chapters/compatibility.adoc @@ -320,7 +320,7 @@ is e.g. visible via Swagger UI and ignored by most tools. See <<240>> about enum value naming conventions. Note, {x-extensible-enum} is a different concept than JSON schema `examples` which is -just a list of few example values, whereas {x-extensible-enum} defines all valid +just a list of a few example values, whereas {x-extensible-enum} defines all valid values (for a specific API and service version) and has the advantage of an extensible full type-range specification that is validated by the service. From 4daa0273830bc14b4c43eb9585bd2273c3f20e52 Mon Sep 17 00:00:00 2001 From: Thomas Frauenstein Date: Thu, 27 Jun 2024 18:05:50 +0200 Subject: [PATCH 9/9] Update chapters/compatibility.adoc Co-authored-by: Tronje Krop --- chapters/compatibility.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/chapters/compatibility.adoc b/chapters/compatibility.adoc index 86724a0c..a1fd25c2 100644 --- a/chapters/compatibility.adoc +++ b/chapters/compatibility.adoc @@ -315,7 +315,7 @@ delivery_methods: ---- *Note:* {x-extensible-enum} is a proprietary extension of the JSON Schema standard that -is e.g. visible via Swagger UI and ignored by most tools. +is e.g. visible via Swagger UI, but ignored by most other tools. See <<240>> about enum value naming conventions.