Separate annotation per enum value

[cowwoc]

Following up on swagger-api/swagger-core#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.

[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: #348 (comment)

[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.

[ralfhandl]

And once we know the answer this is a good place for pointing to it.

[handrews]

@ralfhandl I've tagged this and other issues with schema-object so that we can get a general ruling on how much, if any, schema work we want to keep in this project. I've put it on the agenda for this week's TDC call.

[dabaus]

+1