Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Make descriptions of Enum's self-documenting. #843

Closed
e-lo opened this issue Jul 11, 2023 · 3 comments
Closed

Make descriptions of Enum's self-documenting. #843

e-lo opened this issue Jul 11, 2023 · 3 comments

Comments

@e-lo
Copy link

e-lo commented Jul 11, 2023

As a data spec developer for the TIDES project, I'd like to be able to describe the meaning of various enum values in structured data within the schema.

How it is

There are basically two options for constraining a field to a set of values:

  1. As a constraint
  2. As a rich rdf type

Option 1 - constraint

As it is now, I need to specify an enum as a constraint:

"name": "vehType",
"constraints":{
    "enum": [1,2,3,4,5]
},
"description": "Type of transit vehicle: <br>-  1: 40' motorcoach<br>2: 52' motorcoach<br>3: 40' trolleybus<br>4: 52' trolleybus<br>5: other"

tl;dr; it is brittle and implementation specific :-(

Specifically, the problems are:

  1. Depending on what I use to render my data schema - see our docs for example - the <br> tag may or may not render correctly.
  2. It doesn't allow us to self-document in a way that directly links the values to their descriptions in data...you have to parse a description.

Option 2 - rdfType

Other option would be to define an RDF type.

While this can technically cover our use case, it is cumbersome to implement and not as easy to mentally parse for simple cases (ideally we "KSTSS keep simple things simple stoopid"

How we'd love for it to be.

Option 1 - A new object that defines the enum values keyed to their string equivs

Why a new object instead of self-describing in enum def?
json objects must have strings as keys, but we need to be able to specify enums that aren't strings.

Considerations:

  • In this option, these strings must match one of the string renderings of the enum value, which could be cumbersome to validate and implement.
  • This approach is consistent with adobe's jsonschema2md
"name": "vehType",
"constraints":{
    "enum": [1,2,3,4,5]
},
"meta:enum": {  
   "1": "40' motorcoach" ,
   "2": "52' motorcoach",
   "3": "40' trolleybus",
   "4": "52' trolleybus",
   "5": "other"
},
"description": "Type of transit vehicle"

Option 2 - A new object that defines the enum values as an array

Considerations:

  • In this option, the describeEnum array must be the same length as the enum. This might be straightforward to validate and implement, but could be annoying to define when you have a zillion potential enums.
"name": "vehType",
"constraints":{
    "enum": [1,2,3,4,5],
    "describeEnum": [
         "40' motorcoach" ,
         "52' motorcoach",
         "40' trolleybus",
         "52' trolleybus",
         "other"
   ]
},
"description": "Type of transit vehicle"

Option 3 - Leverage JSON-schema's thoughts on reusable and linkable definitions

This is nice because it allows for a full documentation of the value, but is much more complex to deal with than what is strictly necessary.

"$defs":{
  "vehType": {
       "oneOf": [
          {
            "const": 1,
            "title": "40' motorcoach"
         },
         {
            "const": 2,
            "title":  "52' motorcoach"
         },
          {
            "const": 3,
            "title":  "40' trolleybus",
         },
         {
            "const": 4,
            "title":  "52' trolleybus",
         },
           {
            "const": 5,
            "title":  "other vehicle",
         },
   ]
},
"fields": [{
  "name": "vehType",
  "$ref": "$defs/vehType",
  "description": "Type of transit vehicle"
 }
]
@pschumm
Copy link
Contributor

pschumm commented Sep 17, 2023

@e-lo, you might want to take a look at the pattern proposed in #844. IIUC, the enumLabels property proposed there is very similar to your use of meta:enum in Option 1 above.

@e-lo
Copy link
Author

e-lo commented Sep 18, 2023

IIUC, the enumLabels property proposed there is very similar to your use of meta:enum in Option 1 above.

Indeed it is the same implementation with a different name! 🙌 See my small note about name in there but other than that very slight hesitation I am very supportive and confirm that merging this PR would take care of this issue.

@roll
Copy link
Member

roll commented Jan 3, 2024

#844 has been merged. Thanks a lot for your input!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
Status: Done
Development

No branches or pull requests

3 participants