Descriptions for each enum value

[a-akimov]

TL;DR Moving the discussion from https://github.com/OAI/OpenAPI-Specification/issues/348 to JSON Schema folks.

Hi All,

For enums, we can now only list the values, for example:

cvv_check:
  type: string
  title: CVV check
  description: |
    When processed, result from checking the CVV/CVC value on the transaction.
  enum:
    - D
    - I
    - M
    - N
    - P
    - S
    - U
    - X

But it's a very common practice to explain what these values are, and if there are any important considerations for each value. Because of the current design, we need to duplicate all these values in the description of the enum, which leads to confusion and mistakes. For example:

cvv_check:
  type: string
  title: CVV check
  description: |
    When processed, result from checking the CVV/CVC value on the transaction.
    * `D` - Suspicious transaction
    * `I` - Failed data validation check
    * `M` - Match
    * `N` - No Match
    * `P` - Not Processed
    * `S` - Should have been present
    * `U` - Issuer unable to process request
    * `X` - Card does not support verification
  enum:
    - D
    - I
    - M
    - N
    - P
    - S
    - U
    - X
  maxLength: 1

It would be much nicer to have either this:

cvv_check:
  type: string
  title: CVV check
  description: When processed, result from checking the CVV/CVC value on the transaction.
  enum:
    D: Suspicious transaction
    I: Failed data validation check
    M: Match
    N: No Match
    P: Not Processed
    S: Should have been present
    U: Issuer unable to process request
    X: Card does not support verification
  maxLength: 1

Or better this:

cvv_check:
  type: string
  title: CVV check
  description: When processed, result from checking the CVV/CVC value on the transaction.
  enum:
    - value: D
      description: Suspicious transaction
    - value: I
      description: Failed data validation check
    - value: M:
      description: Match
    - value: N
      description: No Match
    - value: P
      description: Not Processed
    - value: S
      description: Should have been present
    - value: U
      description: Issuer unable to process request
    - value: X
      description: Card does not support verification

According to https://json-schema.org/understanding-json-schema/reference/generic.html#enumerated-values, the enum keyword is the one that "is used to restrict a value to a fixed set of values". Thus, if somebody wants to find all the enums in a schema (manually or programmatically), currently they can just search for "enum" and get all the enum instances.

If we encourage people to use oneOf+const for enums (as was also suggested in https://github.com/OAI/OpenAPI-Specification/issues/348), it will become problematic to find all enums and also to support in relevant tooling.

  oneOf:
    - const: D
      description: Suspicious transaction

I personally really like the idea of the following format, but not sure what's your reasoning against it:

enum:
    - value: D
      description: Suspicious transaction

In general, this issue seems to be super-important for proper adoption of JSON Schema and OpenAPI formats by the documentation communities. Currently, we have to struggle a lot to keep the description in sync with the actual lists of enum values, and see a lot of problems caused by that (e.g. some values are missing, some exposed by mistake, some have spelling errors or mistakenly follow PascalCase instead of camelCase).

Also, the number of comments, votes and mentiones in the original thread https://github.com/OAI/OpenAPI-Specification/issues/348 really speaks to the idea of this problem being important. Please, consider extending JSON schema to properly support descriptions of enum values.