Deprecate x-extensible-enum

[ePaul]

Implements #831.

Also some minor changes to clarify things elsewhere.

[zalando-compr-opensource]

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]

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]

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:

• API Audience specification: rule #219
• Batch response example: rule #152

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]

@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]

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.

[zalando-compr-opensource]

invalid team ID

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

(If this PR is already fixing this, ignore the warning. But preferably fix it
in a PR separate from other changes, as the merge build from this PR will
not give a compliant image.)

You can follow this guideline for help.

[tfrauenstein]

@ePaul Since #839 has been delivered and we upgraded to OpenAPI 3.1, can you please finish this PR. We should also add a hint that x-extensible-enum is continued to be recommended for OAS versions older than OAS 3.1. Thank you!

[ePaul]

I've applied some of the editorial suggestions and made a few more of my own, also indicating the relation to OpenAPI 3.1.

[tfrauenstein]

Yes, I would remove it to avoid redundancies in the same rule context. I also would replace 'similar semantic' by 'same semantics'.

[tfrauenstein]

👍