Deprecate x-extensible-enum (#837)

* Deprecate x-extensible-enum

Implements #831.

* Code review suggestions

Co-authored-by: Thomas Frauenstein <thomas.frauenstein@zalando.de>

* Update PR for october, mention old versions

* apply a few editorial suggestions

* Apply suggestions from code review

editorial: comma, word order

Co-authored-by: Thomas Frauenstein <thomas.frauenstein@zalando.de>

* remove semantic replication.

* split bullet point

* reword "rules apply for legacy"

Co-authored-by: Thomas Frauenstein <thomas.frauenstein@zalando.de>

* Apply suggestion from @ePaul

Co-authored-by: Paŭlo Ebermann <paul.ebermann@zalando.de>

* Update chapters/compatibility.adoc

---------

Co-authored-by: Paul Ebermann <paul@zalando.de>
Co-authored-by: Thomas Frauenstein <thomas.frauenstein@zalando.de>

Author: 3 people

chapters/compatibility.adoc

@@ -51,10 +51,10 @@ services in a backward-compatible way:
   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. The range can be reduced
-  when used as output parameters.
+  when used only as output parameters.
 * `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.
+  not be prepared to handle it. However, `enum` ranges can be extended when used
+  only for input parameters.
 * You <<112>> that are used for output parameters and likely to
   be extended with growing functionality. The API specification should be updated
   first before returning new values.
@@ -124,8 +124,11 @@ 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 parameters (see <<112, rule 112>>) may deliver new values;
-  either be agnostic or provide default behavior for unknown values, and do not eliminate them.
+** Be prepared that <<112, extensible enum>> return parameters
+  may deliver new values;
+  either be agnostic or provide default behavior for unknown values, and
+  do not eliminate them when passed to subsequent {PUT} requests.
+  (This means you cannot simply implement it by using a limited enumeration type like a Java `enum`.)
 ** 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
@@ -289,20 +292,69 @@ level data structures, since they don't support compatible, future extensions.
 
 
 [#112]
-== {SHOULD} use open-ended list of values (`x-extensible-enum`) for enumeration types
+== {SHOULD} use open-ended list of values (via `examples`) for enumeration types
 
 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 recommend to use an open-ended list of values instead
-of an enumeration unless:
+complete and not intended for extension. This means, extending the list of values of
+`enum` is considered an incompatible change, and needs to be aligned with all consumers
+like other incompatible changes.
 
-1. the API has full control of the enumeration values, i.e. the list of values
+To avoid these issues, we recommend to use `enum` only if
+
+1. the API owner has full control of the enumeration values, i.e. the list of values
   does not depend on any external tool or interface, and
 2. the list of values is complete with respect to any thinkable and unthinkable
   future feature.
 
-To specify an open-ended list of values via the {x-extensible-enum} property as follows:
+In all other cases, where additional values are imaginable our recommendation is this:
+
+* Use `examples` with the list of (currently known) values
+* Add `[Extensible enum](https://opensource.zalando.com/restful-api-guidelines/#112).` as a standard prefix to the description.
+
+This indicates that only the listed values are currently possible, but
+consumers need to be aware that this list can be extended without notice
+(see below for details).
+
+[source,yaml]
+----
+delivery_method:
+  type: string
+  examples:
+    - PARCEL
+    - LETTER
+    - EMAIL
+  description: [Extensible enum](https://opensource.zalando.com/restful-api-guidelines/#112). The chosen delivery method of the invoice.
+----
+
+See <<240>> about enum value naming conventions – these apply here too.
+
+
+**Important**:
+
+* API consumers must be prepared for the fact that also other values can be returned
+  with server responses (or be contained in consumed events), and implement a
+  fallback / default behavior for unknown new values, see  <<108>>.
+* API owners must take care to extend these extensible enums in a compatible way, i.e.
+  not changing the semantics of already existing / documented values.
+* API implementations should validate the values provided with the input payload
+  and only accept values listed in `examples`.
+* The list should not be reduced for inputs (that would be an incompatible change).
+* Before additional values are accepted or returned, API owners should update the API description and extend
+  the `examples` list, see <<107>>.
+
+(Note that the last 3 bullet points do not apply for uses of `examples` _without_ the
+ "Extensible enum." prefix in the description – here any value fitting the rest
+ of the schema needs to be expected.)
+
+Note that the plural `examples` on schemas was only introduced with OpenAPI 3.1 (with an update of the JSON schema version referenced).
+APIs defined with older OpenAPI versions can't use this format, and instead need to use
+the {x-extensible-enum} described below↓.
+
+=== Historic Note: `x-extensible-enum`
+
+Previously (until October 2025) this guideline recommended a proprietary
+JSON schema extension {x-extensible-enum} with the same semantic.
+The example above would be specified as follows:
 
 [source,yaml]
 ----
@@ -312,23 +364,20 @@ delivery_methods:
     - PARCEL
     - LETTER
     - EMAIL
+  description: The chosen delivery method of the invoice.
 ----
 
-*Note:* {x-extensible-enum} is a proprietary extension of the JSON Schema standard that 
-is e.g. visible via Swagger UI, but ignored by most other tools.
-
-See <<240>> about enum value naming conventions.
+The "important" rules above apply in an analog way for API providers and consumers using {x-extensible-enum}.
 
-Note, {x-extensible-enum} is a different concept than JSON schema `examples` which is 
-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.
+This rule originated in the time before JSON schema and OpenAPI schema
+had the plural `examples` property (OpenAPI schema had singular `example`,
+JSON schema had neither).
 
-*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. Services should only extend {x-extensible-enum} ranges, and only accept 
-and return values listed in the API specification, i.e. the API specification needs to be updated first  
-before the service accepts/returns new values -- see also <<107>>. 
+The completeness semantic would in theory allow some validation by
+intermediaries (but that was rarely implemented).
+It was visible in a few tools (e.g. Swagger UI), but ignored by most others.
 
+After the team responsible for Nakadi (our Zalando-internal event bus) decided
+to not validate x-extensible-enum, but instead even reject it in event type
+definitions, we (the API guideline maintainers) revisited this rule to
+recommend `examples` instead.

chapters/events.adoc

@@ -952,23 +952,29 @@ maintain compatibility as they will not be in a position to serve
 versioned media types on demand.
 
 For event schema, these are considered backward compatible changes, as
-seen by consumers -
+seen by consumers:
 
 * Adding new optional fields to JSON objects.
 * Changing the order of fields (field order in objects is arbitrary).
 * Changing the order of values with same type in an array.
-* Removing optional fields.
+* Removing optional fields (or rather, stop sending values for the optional
+  field – actually removing it from the schema is not allowed, as otherwise
+  it could be added back with an incompatible type).
 * 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 values to extensible enum fields (see <<112, rule 112>> and <<108, rule 108>>).
 
 These are considered backwards-incompatible changes, as seen by
-consumers -
+consumers:
 
 * Removing required fields from JSON objects.
 * Changing the default value of a field.
 * Changing the type of a field, object, enum or array.
 * Changing the order of values with different type in an array (also
 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. Instead, you <<112>>. 
+* Adding a new optional field to redefine the meaning of a (previously)
+  existing field (also known as a co-occurrence constraint).
+* Adding a value to an `enum` enumeration. Instead, you <<112>>.
+
+When an incompatible change is required, it needs to be aligned with all consumers.
+Only start sending values not covered by the previous schema after all consumers
+are prepared to consume the new values.

chapters/json-guidelines.adoc

@@ -136,12 +136,14 @@ as if it came from the same hand.
 
 Enumerations should be represented as `string` typed OpenAPI definitions of
 request parameters or model properties.
-Enum values (using `enum` or {x-extensible-enum}) need to consistently use
-the upper-snake case format, e.g. `VALUE` or `YET_ANOTHER_VALUE`.
-This approach allows to clearly distinguish values from properties or other elements.
+Enum values (using `enum`, {x-extensible-enum} or extensible enums using `examples`)
+need to consistently use the upper-snake case format, e.g. `VALUE`
+or `YET_ANOTHER_VALUE`.
+This approach allows to clearly distinguish enum values from properties or
+other elements.
 
 **Exception:** This rule does not apply for case sensitive values sourced from outside
-API specification scope, e.g. for language codes from {ISO-639-1}[ISO 639-1], or when
+of the API specification scope, e.g. for language codes from {ISO-639-1}[ISO 639-1], or when
 declaring possible values for a <<137,rule 137>> [`sort` parameter].