Deprecate x-extensible-enum #837

ePaul · 2025-04-29T15:29:47Z

Implements #831.

Also some minor changes to clarify things elsewhere.

Implements #831.

zalando-compr-opensource · 2025-04-29T15:29:51Z

invalid team ID

The team ID in your .zappr.yaml file does not appear to be valid. Please, fix
this before team ID checks will be added back into ComPR's specification check.

You can follow this guideline for help.

zalando-compr-opensource · 2025-04-29T15:29:51Z

invalid team ID

The team ID in your .zappr.yaml file does not appear to be valid. Please, fix
this before team ID checks will be added back into ComPR's specification check.

You can follow this guideline for help.

zalando-compr-opensource · 2025-04-29T15:29:51Z

invalid team ID

The team ID in your .zappr.yaml file does not appear to be valid. Please, fix
this before team ID checks will be added back into ComPR's specification check.

You can follow this guideline for help.

tfrauenstein

Thanks a lot for the PR -- LGTM!
I provided some (mostly editorial) change proposals.

There are other occurrences of x-extensible-enum in the following rules that need to be updated:

The Event Type specification: rule #197 also uses x-extensible-enum. However, the rule anyway needs to be cleaned-up -- see Issue: Optimize the Event Guidelines for its usage with Nakadi. So I propose to handle this via a separate PR for the Event Guideline Clean-Up issue.

Additionally, I propose to add a log entry to the Change History.

tfrauenstein · 2025-05-05T15:37:32Z

chapters/compatibility.adoc

@@ -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 "extensible enum" return parameters (see <<112, rule 112>>)


Suggested change

** Be prepared that "extensible enum" return parameters (see <<112, rule 112>>)

** Be prepared that <<112, extensible enum>> return parameters

chapters/compatibility.adoc

tfrauenstein · 2025-05-05T15:44:24Z

chapters/compatibility.adoc

+** Be prepared that "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 if needed for subsequent {PUT} requests.


Suggested change

do not eliminate them if needed for subsequent {PUT} requests.

do not eliminate them when passed with subsequent {PUT} requests.

chapters/compatibility.adoc

tfrauenstein · 2025-05-05T16:26:12Z

chapters/compatibility.adoc

+intermediaries (but that was rarely implemented).
+It was visible in a few tools (e.g. Swagger UI), but ignored by most others.
+
+An open-ended list of values was specified as follows:


Would move this example up after ... with a similar semantic:.

tfrauenstein · 2025-05-05T16:28:18Z

chapters/compatibility.adoc


+We also thought we could have some validations (e.g. by our event bus Nakadi),


Suggested change

We also thought we could have some validations (e.g. by our event bus Nakadi),

We also thought we could provide validations in our infrastructure

chapters/compatibility.adoc

tfrauenstein · 2025-05-05T16:32:27Z

chapters/events.adoc

@@ -953,23 +953,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


Suggested change

For event schema, these are considered backward compatible changes, as

For event schema, these are considered full compatible changes, as

Hmm, Nakadi has the three levels of compatibility (compatible, forward, none), while we here only describe the difference between the first two. Not sure if naming these "full compatible" and "incompatible" is the right thing.

Let us use the Nakadi wording, i.e. compatible instead of full compatible (= backward and forward compatible). Let us use non-compatibel as opposed to compatible.
Let us avoid defining the other 'compatibility modes' of Nakadi -- will be linked when we do the Nakadi / Guideline clean-up.

tfrauenstein · 2025-05-05T16:34:36Z

chapters/events.adoc

 * 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


Suggested change

These are considered backwards-incompatible changes, as seen by

These are considered *in*compatible changes, as seen by

Co-authored-by: Thomas Frauenstein <[email protected]>

tfrauenstein · 2025-05-07T15:38:46Z

@ePaul I just discovered that 'examples' in OpenAPI 3.0 is not yet consistent with JSON Schema -- this was only fixed with OpenAPI 3.1! In OpenAPI 3.0 examples is a map of named examples, and not simply an array of examples like in JSON Schema. In OpenAPI 3.1 examples in data object schema definitions is done like in JSON Schema (as array), but OpenAPI 3.1 still supports example and examples outside the schema — specifically under the media type object (like application/json) in the 'old way' as map (see working-with-examples ). If we want to stick to OpenAPI 3.0 as status-quo, we need to change the examples. I also created an Issue: OpenAPI 3.1 Upgrade for discussion in the guild.

ePaul · 2025-05-27T12:54:09Z

As OpenAPI 3.0 doesn't have examples in the schema object, we can't really use that before we generally recommend 3.1 (or later). Putting on hold, waiting for #839.

Deprecate x-extensible-enum

8d935cd

Implements #831.

ePaul added guideline-change zally-change major Major feature changes or updates, e.g. feature rollout to a new country, new API calls. labels Apr 29, 2025

tfrauenstein reviewed May 6, 2025

View reviewed changes

Code review suggestions

c1e8eb1

Co-authored-by: Thomas Frauenstein <[email protected]>

ePaul marked this pull request as draft May 27, 2025 12:52

	** Be prepared that "extensible enum" return parameters (see <<112, rule 112>>)
	** Be prepared that <<112, extensible enum>> return parameters

	do not eliminate them if needed for subsequent {PUT} requests.
	do not eliminate them when passed with subsequent {PUT} requests.


		We also thought we could have some validations (e.g. by our event bus Nakadi),

	We also thought we could have some validations (e.g. by our event bus Nakadi),
	We also thought we could provide validations in our infrastructure

		@@ -953,23 +953,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

	For event schema, these are considered backward compatible changes, as
	For event schema, these are considered full compatible changes, as

	These are considered backwards-incompatible changes, as seen by
	These are considered incompatible changes, as seen by

Deprecate x-extensible-enum #837

Are you sure you want to change the base?

Deprecate x-extensible-enum #837

Uh oh!

Conversation

ePaul commented Apr 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

zalando-compr-opensource bot commented Apr 29, 2025

invalid team ID

Uh oh!

zalando-compr-opensource bot commented Apr 29, 2025

invalid team ID

Uh oh!

zalando-compr-opensource bot commented Apr 29, 2025

invalid team ID

Uh oh!

tfrauenstein left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tfrauenstein commented May 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ePaul commented May 27, 2025

Uh oh!

Uh oh!

ePaul commented Apr 29, 2025 •

edited

Loading

tfrauenstein commented May 7, 2025 •

edited

Loading