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.