annotating enum values

[Daniel Davidson]

What is a good approach to passing enums? The concept of enum in json schema seems a bit different than that in general programming since enum in json schema can be anything. But assume I want to store just the discriminator that specifies exactly one of a set of possibilities. I can use enum with a list of unique strings or a list of unique numbers. For serialization and storage, numbers are preferred. But for documentation/GUI display strings are more appropriate. Assume I have this schema defining a quantity bin that will support interpolation from _x_ input values based on an interpolation type (linear, cubic, step). What is the best way in Json Schema to annotate or document the fact that linear = 0, cubic = 1, step = 2?

Thanks,

Dan

{

  "definitions" : {

    ...

    "interpolationType": {

      "enum": [

        0,

        1,

        2

      ]

    },

    ...

} 

[Geraint]

The pattern I would use there would actually be to use meaningful enum values.  In this case, instead of 0/1/2, I would use "linear"/"cubic"/"step".

In a lot of storage engines, enums are stored as numbers for compactness, but the whole point of an enum is that it is stored differently to how it is presented, because inscrutable numbers are unhelpful.

For example, I might get an incoming request like this:

PUT /items/123

{

    "id": 123,

    "title": "Test item",

    "nodeType": "annotation"      <--- this is an enum of "annotation"/"document"/"collection"

}

My server processes that, and ends up with the following MySQL query:

UPDATE my_items SET title='Test item', nodeType='annotation', ...  WHERE id=123

Since the nodeType column is an enum, MySQL actually stores it as an integer - so I feel I have a nice balance of storing as a compact number, but the API outputs something friendly which the UI can use.

I can see that this might be different if you're storing your JSON data in MongoDB, because that has no idea of enums for particular fields...

[Philippe Marsteau]

One issue I have with enum is the distinction between keys (string or integer) that may be a enum code, vs a meaningful description of each potential value. For property value, schema allows storing a description or title metadata. To my knowledge, we can't for enum individual values. This becomes an issue if codes/enum values are to be exposed in a UI (think i18n, like getting description/title of enum value in a given language).

The data payload would only contain the enum value/code; metadata (schema) would contain description or displayable title associated to enum code.

Phil

[Geraint]

Well, we don't really deal with internationalisation of titles anyway... or were you thinking of serving up lots of different versions of the schema, each describing the same format/API, but with different titles? :S

As a workaround for what you want, there's:

{

    "oneOf": [

        {

            "title": "Option 1",

            "enum": [1]

        },

        {

            "title": "Option 2",

            "enum": [2]

        }

    ]

}

... but that's not ideal.

[Philippe Marsteau]

I18n matters, at least in enterprise business. The way we anticipated tackling this was exposing a json schema per language. In fact json schema is written once but all title / description are replaced with tokens. User sends language preference (eg. using Accept Language http header) and server dynamically replaced tokens with appropriate lang translation.

But for enum, it is a value (not a meta info like title or description) a payload may send or expect receiving, no matter the schema language.

Ideally, extending schema to allow each enum value to have meta attribute (eg title) would fix it.

[Geraint]

That l18n method is better than I thought.  I've heard of people ending up with /schemas/en/blah, /schemas/fr/blah, etc.  Accept Language modifying the same document sounds like a pretty decent solution.

That's a very good point about "enum", though.  Would you be thinking of a different property, like "enumTitles", or somehow changing the syntax of "enum"?  I'm personally unsure about syntax changes.

[Daniel Davidson]

Maybe another alternative would be the below. The idea is to use convention for locating comments on the values in the enums. I guess it depends on how you use the schema beyond just validation. For my case I decided to Go with Geraint's recommendation of using strings in the schema instead of numbers, but the serialization will be numbers (mongo will be a target for me). But I'll be using the schema for code generation as opposed to runtime validation, so it should be fine.

    {

      "definitions" : {

        "interpolationType" : {

          "enum" : [ 0, 1, 2 ]

        }

      },

      "il8n" : {

        "en" : {

          "interpolationType" : {

             "0" : "For representing linear interpolation",

             "1" : "For cubic interpolation, requiring three points to work",

             "2" : "Step function"

[Geraint]

I would personally prefer the info to be in the sub-schema (e.g. next to "enum", there might be "enumTitles" or something).

The localisation stuff is interesting - we currently have strings in "title" and "description" (and would have them in "enumTitles" or whatever).  If we wanted to write multi-lingual schemas (which we may or may not want to - I quite like Phillipe's "Accept Language" method), then those strings could optionally be replaced with multi-lingual maps, e.g.
{
    "title": {"en": "Example data format", "de": "Beispiel Datenformat"},
    ...
}

That would make for incredibly chunky schemas, though.