Separate annotation per enum value

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.

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

@cowwoc

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

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

+1

@fehguy

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

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.

+1

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

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

+1

@drewish

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.

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

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

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/

@lornajane

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

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.

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

@ralfhandl

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

+1

Add description table for RT errors (#56)

As enums are part of the JSON Schema specification, whenever JSON Schema gets this feature, OpenAPI will pick it up too.

Navigation Menu

Repository navigation

Separate annotation per enum value #348

14 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Separate annotation per enum value #348

Description

Activity

bgrant0607 commented on Aug 18, 2015

fehguy commented on Aug 18, 2015

cowwoc commented on Aug 18, 2015

henkosch commented on Oct 1, 2015

jontejj commented on Nov 6, 2015

drewish commented on Jan 20, 2016

ralfhandl commented on Feb 3, 2016

webron commented on Feb 24, 2016

webron commented on Feb 24, 2016

cabbonizio commented on Feb 25, 2016

ePaul commented on Feb 28, 2016

webron commented on Jul 21, 2016

giuliopulina commented on Oct 12, 2017

14 remaining items

lornajane commented on Nov 22, 2023

handrews commented on Jan 26, 2024

lornajane commented on Jan 28, 2024

ralfhandl commented on Jan 29, 2024

handrews commented on Jan 29, 2024

dabaus commented on Jan 17, 2025

itbencn commented on May 28, 2025

mnemitz commented on Jul 25, 2025

karenetheridge commented on Aug 16, 2025

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions