Added recommandation against enums

[tkrop]

Fixes #119

[ePaul]

Maybe adapt the compatibility section which mentions this, too.

[tkrop]

Added links and improved wording.

[ePaul]

During the meeting we discussed whether the name x-extensible-enum for this property is really the right thing (no decision was yet done about this).

I originally proposed this name for the extension property in the guidelines, and took the syntax from Swagger's enum property (which came from JSON schema). In JSON schema (and thus also in Swagger/OpenAPI) enum restricts the values to just the given values – which is useful for validation, and in code-generating tools is also used for generating enums in programming languages.

Some arguments for/against changing:

• "Extensible enum" is an oxymoron, and thus a bad name.
• What we have here is basically a list of examples (for which possibly some meaning is already defined – though not documented), not a list of all possible examples (which would be an enumeration).
• We already established this name, and it is used in several API definitions already. Changing it now would confuse people.
• There is no (known) software support for this property name, changing it would not break any API (nor implementation).

@ALL What would be better names? Just x-examples? (Other proposals welcome.)

If we are already changing the name of the property, we could consider to add a description for each item. The next version of OpenAPI likely will have be some way of documenting each enum item, maybe we want to do this similarly? (Though that is not yet finished.)

[whiskeysierra]

@ALL What would be better names? Just x-examples? (Other proposals welcome.)

x-samples, pun intended

[whiskeysierra]

+1 on using an object for this to add descriptions per value.

[tkrop]

+1 on using an object for this to add descriptions per value.

@whiskeysierra hmm, can you give an example, what you have in mind?

[ePaul]

@tkrop
One possible way (which would work not just for strings, also for whole objects or similar):

  Event:
    description:
      An event which will be delivered to Nakadi (or other event sinks),
      together with some metadata used by Tarbela.
    type: object
    properties:
      [...]
      delivery_status:
        type: string
        description: |
          The delivery status of an event.
       x-samples:
        - value: NEW
          description:
             the event was created in the producer, and not yet tried to publish.
        - value: SENT
          description: the event was successfully published to the event sink.
        - value: ERROR
          description: something did go wrong with publishing the event.

For enum-like string properties something like this would also work:

properties:
  delivery_status:
    type: string
    description: the code of the discount type for this discount condition.
       x-samples:
         NEW: the event was created in the producer, and not yet tried to publish.
         SENT: the event was successfully published to the event sink.
         ERROR: something did go wrong with publishing the event.

(This could go into Tarbela's producer API).

[tkrop]

@ePaul @whiskeysierra great suggestion. Which one should I pick for example? both?

[whiskeysierra]

The first one is more powerful, I'd say. But I don't like to have Java-idomatic enum values (upper underscore). I think snake case or lower hyphen would be a better fit.

[tkrop]

@whiskeysierra I think it is not only Java, but many other programming languages too ... event if http://blog.josephwilk.net/rhetorical-programming/why-are-you-shouting-programmer.html isn't a good reference ;)

@ALL I'm willing to change it to lower snake case if some more reviewers support this request.

[ePaul]

The example was from an existing API, which used upper-case values. For an example in the Guidelines of how this should look of course you can write them differently. (I guess we still need some explanation text around this.)

[whiskeysierra]

👍

[fmueller]

👍