Deprecate x-extensible-enum

[ePaul]

Background

Nakadi, our Zalando-internal event bus, recently started to reject event schemas using x-extensible-enum. (As part of introducing a stricter schema validation.)
The team suggests to replace that by either enum or examples.

This leaves us with rule 112 being not supported anymore by our main event bus.

We discussed this today in the API guild meeting.

Planned Change

We'll deprecate the x-extensible-enum schema property.

• Rule 112 will be changed to recommend using examples together with "Extensible enum" in the description, but we keep the definition here of what x-extensible-enum means, as a reference for people who find it in existing APIs. We also mention that it doesn't work in Nakadi.
• Rules 107/108 will be adjusted, as well as 240, 209.
• Examples which use x-extensible-enum need to be adjusted.

Afterwards, Zally's rules also need to be adjusted.

[tfrauenstein]

Yes. Let us also motivate why x-extensible-enum is not needed anymore.
a) JSON schema extended: x-extensible-enum was a proprietary standard extension at a time when examples was not yet part of JSON Schema. It is now time to return the feature to the (extended) standard.
b) No automated validations: There are not infrastructure services (e.g. Nakadi) that do the validations based on the schema definition. We generally expect that the validations are done on server side implementing the schema definition.

[tkrop]

Lets not completely remove x-extensible-enum yet, but keep backward compatibility. We should just primarily refer to using examples and name x-extensible-enum as the alternative for the older APIs using versions where examples is not available. x-extensible-enum is doing its job, but examples has advantages - if it is sufficiently supported by the UI some day.

Up to this day, I would anyhow suggest to put the full list of values also into the description including a description of the semantic of each value to guide users correctly on the usage. This is currently neither supported by the x-extensible-enum nor by examples and majorly missing our guideline - I think. Some example how this should look like may be found in the software-registry.