how do i describe the values for an enum ?

22,832 views
Skip to first unread message

ashutosh raina

unread,
Jan 17, 2012, 9:08:26 AM1/17/12
to JSON Schema
I have the folllwing
"Enum": [
"22PC",
"42GP",
"45GP",
"45UP",
"22GP"]

in my JOSN Schema. I want to be able to add some text describing what
these values mean. What could be the best way of doing this ?

Xample

unread,
Jan 17, 2012, 2:08:45 PM1/17/12
to json-...@googlegroups.com
Well, the schema describes the instance. If you would like to describe your schema you should then create a (or extends the) schema of the schema, where you would then have for this particular enum:

{ "type":"array", "items":[ {"type":"string", "description":"description of 22PC"}, {"type":"string", "description":"description of 42GP"}, {"type":"string", "description":"description of 45GP"}, {"type":"string", "description":"description of 45UP"}, {"type":"string", "description":"description of 22GP"} ], "additionalItems":false }

Think that a string in itself have no description as long as it is not associated to a schema (which explains why we are talking about schemaSchema)

ashutosh raina

unread,
Jan 19, 2012, 6:40:11 AM1/19/12
to JSON Schema

Not sure if you got my questions perfectly. I am not talking about
describing the schema . A property inside the schema can have an enum.
This enum will have some elements . Now, i would like to describe
these elements , with a one line description. If i am reading it
correctly , you are asking me to have each of the elements as a schema
and the description will actually from there.
Again, hopefully a simple solution will be desirable.

Francis Galiegue

unread,
Jan 19, 2012, 9:03:27 AM1/19/12
to json-...@googlegroups.com

The short answer is, you cannot do that. "description", which is the
closest to what you would want, is a "first level" object of a schema
and applies to the schema itself.

The long answer is, if you use a JSON parser which supports C++-style
comments (which are normally not legal in JSON) then you may add
comments to describe your enum values. But your schema would then
become unusable by third parties -- because they won't be JSON
anymomre.

--
Francis Galiegue, fgal...@gmail.com
"It seems obvious [...] that at least some 'business intelligence'
tools invest so much intelligence on the business side that they have
nothing left for generating SQL queries" (Stéphane Faroult, in "The
Art of SQL", ISBN 0-596-00894-5)

Chris Miles

unread,
Jan 19, 2012, 4:10:08 PM1/19/12
to json-...@googlegroups.com
The element with the enum can have its own description property; you
'just' have to pack your descriptions in it. I often do "description" :
"XX: xx details, YY: yy details, etc"

Haykel BEN JEMIA

unread,
Jan 20, 2012, 2:15:21 AM1/20/12
to JSON Schema
What about introducing enums to the schema, something like
'restriction' in XSD? I'm still very new to the JSON schema so I can't
give a real example, but I can imagine something like {"type":
"string", "restriction": ["22PC","42GP","45GP","45UP","22GP"]}. Sorry
if this is incorrect, I just want to say that I find that enums (or
restrictions) are very important to enhance validation.

Francis Galiegue

unread,
Jan 20, 2012, 3:13:03 AM1/20/12
to json-...@googlegroups.com

But the "enum" keyword does that already. In fact, you don't even need
the "type" in this case, just:

{ "enum": [ "22PC","42GP","45GP","45UP","22GP" ] }

"enum" lists the possible values for the JSON node at this point, you
may have any valid JSON fragment in an enum:

{ "enum": [ 4, null, false, 2.02, [ 3, "helloworld" ] ] }

Xample

unread,
Jan 20, 2012, 3:50:53 AM1/20/12
to json-...@googlegroups.com
Okay, there is one possible workaround to do what you are actually searching for (and avoiding using a schema schema):
You can make use of an array of "type", forcing the content to match at least one of those described type. (We use the enum as as single item to force the string content to match the right value).

Here is the way to achieve this
{ type:[ {enum:["22PC"], description:"a description for the first enum"}, {enum:["42GP"], description:"a description for the second enum"},
{enum:["45GP"], description:"a description for the third enum"}, {enum:["45UP"], description:"a description for the fourth enum"}, {enum:["22GP"], description:"a description for the fifth enum"} ] }

enjoy!

Francis Galiegue

unread,
Jan 20, 2012, 4:03:13 AM1/20/12
to json-...@googlegroups.com

Please remember that keys in a JSON Object MUST be strings: { "type":
[ { "enum": blablabla

Otherwise your input is not valid JSON.

Xample

unread,
Jan 20, 2012, 4:50:15 AM1/20/12
to json-...@googlegroups.com
You are right, here is the schema for the purists.

ashutosh raina

unread,
Jan 22, 2012, 11:52:29 AM1/22/12
to JSON Schema
hello all,

i might have sparked a good debate :). I will try the last solution
provided by Xample.

Sky Sanders

unread,
Jan 22, 2012, 1:20:34 PM1/22/12
to json-...@googlegroups.com
I know I am going to catch a lot of flack for this but this is how I represent a dot net enum in json-schema. if it is a bitmask, 'flags', enum i just use the catch-all 'format' attribute to specify.

    "ErrorCode": {
        "id": "ErrorCode",
        "type": "integer",
        "enum": [
        0, 403, 500, 4000, 4001, 4002, 4003, 4004, 4010, 4011, 5001, 5002],
        "options": [{
            "value": 0,
            "label": "NoError",
            "description": "No error has occured."
        }, {
            "value": 403,
            "label": "Forbidden",
            "description": "The server understood the request, but is refusing to fulfill it."
        }, {
            "value": 500,
            "label": "InternalServerError",
            "description": "An unexpected condition was encountered by the server preventing it from fulfilling the request."
        }, {
            "value": 4000,
            "label": "InvalidParameterType",
            "description": "Server could not understand request due to an invalid parameter type."
        }, {
            "value": 4001,
            "label": "ParameterMissing",
            "description": "Server could not understand request due to a missing parameter."
        }, {
            "value": 4002,
            "label": "InvalidParameterValue",
            "description": "Server could not understand request due to an invalid parameter value."
        }, {
            "value": 4003,
            "label": "InvalidJsonRequest",
            "description": "Server could not understand request due to an invalid JSON request."
        }, {
            "value": 4004,
            "label": "InvalidJsonRequestCaseFormat",
            "description": "Server could not understand request due to an invalid JSON case format."
        }, {
            "value": 4010,
            "label": "InvalidCredentials",
            "description": "The credentials used to authenticate are invalid. Either the username, password or both are incorrect."
        }, {
            "value": 4011,
            "label": "InvalidSession",
            "description": "The session credentials supplied are invalid."
        }, {
            "value": 5001,
            "label": "NoDataAvailable",
            "description": "There is no data available."
        }, {
            "value": 5002,
            "label": "Throttling",
            "description": "Request has been throttled."
        }],
        "description": "This is a description of the ErrorCode enum.",
        "demoValue": "403"
    }

Three D Fish

unread,
May 7, 2019, 4:08:02 AM5/7/19
to JSON Schema
I would say that this is close, however, I believe a better way has been found, as discussed here:  https://github.com/json-schema-org/json-schema-spec/issues/57

for example:

    {
       "type": "string",
       "oneOf": [
           {"const": "22PC", "description": "description of value"},
           {"const": "42GP", "description": "description of value"},
           {"const": "45GP", "description": "description of value"},
           {"const": "45UP", "description": "description of value"},
           {"const": "22GP", "description": "description of value"}
       ]
Reply all
Reply to author
Forward
0 new messages