Guidance on extensible enums

[JonKohler]

hey Zalando team! We're looking to leverage some of the great restful API guidance that you all have produced as part of an effort to standardize our rest API design at our company, and I had a quick question about extensible enums, as defined here: https://opensource.zalando.com/restful-api-guidelines/#112

Earlier this year, I referenced this configuration in a feature request to openapi upstream, here: OAI/OpenAPI-Specification#1552

Specifically around upstream adopting some sort of extensible enum support.

Since then, I've been looking around more at what some others are doing, and I've come across the Microsoft Azure way of doing things, here: https://github.com/Azure/autorest/blob/master/docs/extensions/readme.md#x-ms-enum

IMHO, I really like the what that Azure has approached this problem, as not only do you work around the static enum issues that have plagued coding styles forever, but you get the opportunity to add even more extensiblity than just a simple growable list.

I'm curious to get your teams sage guidance on this, and see if there is a way to potentially parlay all of these efforts together to come up with a single community standard, that then we could perhaps help the openapi upstream community adopt.

Lemme know!

jon@nutanix.com, github.com/nutanix

[tkrop]

@JonKohler Thanks for sharing this with us.

We decided for adding the extension keyword x-extensible-enum, because we didn't want to change the well known semantic of the enum keyword. This was based on the necessity to express an open ended list of values in an easy human readable way. This is triggered by the fact that our guideline is based on focusing the API specification on human readability instead of obscuring it by code generation features. That's also why

deliver_methods:
  type: string
  anyOf:
  - enum:
    - parcel
    - letter
    - email
  - {}

doesn't fit well to our needs. The same with x-ms-enum, which is to much aligned to code generation. The drawback is, that we often have to remind our engineers about using x-extensible-enum. They tend to forget, that - at least in our company - the common case are extensible enum values. From this perspective x-ms-enum is not using the best default value for us. So we would prefer a by default open definition.

Personally, I can live without description on enumeration values, as I think if the value is not self-speaking it should be changed, but I could understand requirements for more description.

[tkrop]

Haven't had the time to discuss this in last guild meeting. Trying to do it next week.

[ePaul]

I somehow missed this until now ...

JSON schema's enum (and by inheritance, OpenAPI's one) bascially is a guarantee that no other than the listed values will be ever used. Clients can rely on it (e.g. by mapping it to an enum in their implementation, or just by coding custom logic which supposes no other values can happen), and therefore this part of an API can not be extended in a compatible way (when it is used in an output – for input parameters it can't be made smaller).

x-extensible-enum was our answer to that, maybe a bit unfortunately named. It basically is a list of examples – consumers always need to be ready to accept also other values (both from a syntactic point of view as from a business logic one).

One could say that it is now obsolete because OpenAPI 3.0's examples property serves a similar purpose ... but unfortunately that is only usable for top-level things like parameters or request bodies, not for single value schemas.

As I understand, the approach by Azure is to use just OpenAPI's (and JSON schema's) enum in the way we are using x-extensible-enum, while defining a separate attribute to make it a "real enum" in any generated implementations.

As said by Tronje, we wanted to avoid redefining the meaning enum (especially as it is already supported by code generators).

[tkrop]

@JonKohler any progress on the oneOf/const solution for x-extensible-enum?

I noted that the schema object is inconsistent in the way that it is based on JSON Schema Validation (Draft 6) without const.

I think we could commit to this, as we although see the need for documenting enums - fixed set as well as extensible ones. Unfortunately, JSON Schema Validation (Draft 7) does not solve this consistently, as enum is still an undocumented array of values. Any idea how to solve this?

[ePaul]

Closing, as there is currently nothing we want/can do here.

[tkrop]

@JonKohler please reopen this issue, if you have new information about this.

[LasneF]

issue about introducing x-extensible-enum is that it breaks the semantic of at a point of time a restriction of the value of a string. and here will be discarded by most of the JSon Schema validator , that is kind of worrying