Separate annotation per enum value

[cowwoc]

Following up on https://github.com/swagger-api/swagger-core/issues/1012 I'd like a service to return an Enum type and then document enum values by providing a separate annotation per value. I expect Swagger to aggregate these annotations so that all values and their descriptions are listed in the resulting documentation.

[bgrant0607]

+1. (Yes, github should have a voting button.)

[fehguy]

@cowwoc @bgrant0607 how would you propose this is represented in the description? For example, the current enum system uses primitive arrays:

myValue:
  properties:
    statusFields:
       type: string
       enum:
          - 1
          - 2

I suppose these could be objects, but we'll have to be prescriptive of the structure.

[cowwoc]

Each enum entry could be an object with name and documentation properties (or however you want to call it).

[henkosch]

+1

[jontejj]

@fehguy @cowwoc Or there could be a separate enumDescriptions array (keeping backwards compatibility) where the amount of descriptions should match the amount of enums. Perhaps it's not very pretty but it would be a way forward.

[drewish]

I would love to be able to use an object/hash for enums. For example I've got an app with credit card transactions that use rather cryptic values for the CVV checks. Here's what I'm forced to do to document it:

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 just have:

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

Clients could either just use the keys and ignore the values, or show both in a <select> HTML element.

[ralfhandl]

+1

[webron]

I think there's a similar proposal for this for draft 5 of JSON Schema, will look for it.

[webron]

Parent issue: json-schema-org/json-schema-spec#579

[cabbonizio]

+1

[ePaul]

Currently the enum feature allows any kind of JSON thing in it – objects, arrays, strings, numbers, even mixed (though I'm not sure if things other than strings are supported by various toolings).

With the map variant proposed by @drewish we would be limited to strings. (This is not necessarily a problem for most cases, I just wanted to point it out.)

A more flexible version (though more verbose) would be to have an array of value/description pairs:

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

I guess this corresponds to what @cowwoc proposed.

[webron]

Tackling PR: json-schema-org/json-schema-spec#741

[giuliopulina]

I would be interested in this feature: I know it's not supported, are there any plans to introduce this in the future?

[handrews]

The recommended way in JSON Schema to do this (using draft-06's const, but one-element enums work in OpenAPI and are effectively constants) is:

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

[giuliopulina]

Thanks! This seems clean, but unfortunately seems also not supported in swagger-codegen 2.2.3 (I just tried) :(

[Altreus]

I came here looking to see how I could do this - I wanted to be able to programmatically get the labels for options and thus build a <select>. I just wanted to weigh in.

The concern for maintaining backward-compatibility for enum is legitimate and it doesn't look like we've used options yet, so maybe that could be a more formal way of specifying this? Essentially it has the exact same semantics as an HTML select box, inasmuch as the select box doesn't know or care how the actual values are to be treated. In HTML, all option values are strings, and are returned as such, and the application semantics determine whether to convert it to an integer or not.

Finger-in-the-air feeling is that oneOf could be difficult to optimise for this situation, and enumDescriptions just sounds clumsy (without meaning offence). Plus, options recalls the semantics of HTML, which this closely resembles. I definitely agree that a new property that implies these semantics is a good idea.

[handrews]

With #1977 the idiom I provided above will be supported in OAS 3.1.

There may be further work to do on how to best recognize that idiom in tooling, but I think that would be best tracked as new issues. Possibly initially filed against tools as OAS 3.1 becomes supported, and then back here if a good approach emerges.

@webron can we close this? If not, what should we do with things that are essentially "let's see what happens after OAS 3.1?" which may or may not require further action?

[a-akimov]

@webron, @handrews – Can you please consider this improvement once again, for the version 3.1.0? I believe that the suggested solution is more a workaround and might postpone proper adoption and implementation of enums in the OpenAPI format.

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 the API (manually or programmatically), currently they can just search for enum and get all the enum instances.

If we encourage people to use a new construction like this for enums:

  oneOf:
    - const: D
      description: Suspicious transaction

it will become problematic to find all enums and also to support in relevant tooling.

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 the OpenAPI format 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).

Please offer a good solution to this problem in OpenAPI 3.1. This new version is already a breakthrough, but maybe we can make it even better? :-)

[ahx]

@a-akimov Since we don't want to have differences between JSON Schema and "OAS flavoured JSON Schema" again, this looks like a an issue that should be discussed in the JSON Schema project. The advantage in sticking to standard JSON Schema is that we can use standard JSON Schema validators when building tools.

[darrelmiller]

@OAI/tsc (or at least some subset of it) agrees with @ahx assessment.

[a-akimov]

As suggested by @ahx and @OAI/tsc (some subset of it), I've initiated this discussion with JSON Schema folks. If anyone is interested in contributing, please leave your comments in https://github.com/json-schema-org/json-schema-vocabularies/issues/47.

[Tasselhoff]

As suggested by @ahx and @OAI/tsc (some subset of it), I've initiated this discussion with JSON Schema folks. If anyone is interested in contributing, please leave your comments in json-schema-org/json-schema-vocabularies#47.

It doesn't appear to have got any further though. This is really important for documentation purposes (as you all know).

[pedy711]

Hi all, could you please provide an example of an enum with a label if it is already possible in OAS?

[jearton]

+1

[MikeRalphson]

@pedy711 @jearton the solution for OAS 3.1 is as detailed here: https://github.com/OAI/OpenAPI-Specification/issues/348#issuecomment-336194030

[jearton]

@pedy711 @jearton the solution for OAS 3.1 is as detailed here: #348 (comment)

But Swagger-UI doesn't support OAS3.1 yet.

[handrews]

This is the equivalent in OAS 3.0 (although of course, if tooling vendors don't support it, or OAS 3.1, that's something you have to raise on their repos as we cannot do anything about it from here - the Swagger UI issue for OAS 3.1 support is swagger-api/swagger-ui#5891).

Anyway, in OAS 3.0 you can just use 1-element enums in place of const:

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

[lornajane]

This is a real problem, at Redocly we have this extension x-enumDescriptions to try to help the situation, but it's not great since it only supports simple types - sharing it as an example of usage "in the wild" https://redocly.com/docs/api-reference-docs/specification-extensions/x-enum-descriptions/

[handrews]

@lornajane it's definitely a real problem, but should we hold onto this or declare it to be a JSON Schema issue and not one that we will address? We could consider adding another JSON Schema extension keyword to 3.2, but that just starts widening the gap with standard JSON Schema again.

[lornajane]

I vote we hold onto this for now, it's not obvious what the best answer is, but I think it would be a good addition to have at some point - for docs tools particularly where the extra context can really help users.