-
Notifications
You must be signed in to change notification settings - Fork 117
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
Comments
2 tasks
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. |
#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
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:
Option 1 -
constraint
As it is now, I need to specify an enum as a constraint:
tl;dr; it is brittle and implementation specific :-(
Specifically, the problems are:
<br>
tag may or may not render correctly.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:
jsonschema2md
Option 2 - A new object that defines the enum values as an array
Considerations:
describeEnum
array must be the same length as theenum
. This might be straightforward to validate and implement, but could be annoying to define when you have a zillion potential enums.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.
The text was updated successfully, but these errors were encountered: