JSON

(one of the InLOC Bindings)

This work may be superseded by JSON-LD

One real possibility is to define something more nearly optimal, coordinating well with the relevant parts of Mozilla Open Badges and with xAPI. Join us if you are interested! (Write to Simon Grant.)

We are looking at JSON-LD for the new binding. Please let Simon know if you are interested in helping.

The InLOC JSON Binding

Introduction

This is a provisional binding of InLOC using JSON schema and sample examples. For more information about JSON, see the further reading section below.

It should be remembered that the primary purpose of JSON is not to support human readability, but to transfer information between, typically, clients and servers as part of a web service. For this reason, consistency of the format is more important than human readability or conciseness.

A "property" in the informarion model is represented in JSON as a key:value pair. The term "property" is used in the context of being a property of an object, and the term "key:value pair" is used when the focus in on the pair itself.

JSON Schema

The InLOC JSON Schema is defined basing on current UML diagram (in the Information Model). This is an early draft, open for comment, feedback and improvements.

Recursion for child LOCstructures objects is supported. Issues are describe in the "Known issues" section below.

JSON examples

JSON root object

The LOCstructure may be at the root, as it is in XML. However, as the purpose of JSON is often to transfer small amounts of specific information between software components, so there is no defined fixed root for an InLOC JSON structure.

LOC structure and LOC definitions

Properties of LOCstructure and LOCdefinition objects include the mandatory id, and an optional language key:value pair, for use if there is a sole or default language for strings within the JSON structure.

Both LOCstructure and LOCdefinition are JSON objects using a common list of optional properties, corresponding to elements in the XML binding. Each element name in XML corresponds to a key in JSON. In this list, the corresponding multiplicity and value type is given after the colon (':').

  • "extraID": multiple - array of IRI
  • "title": unique - language map
  • "abbr": unique - language map
  • "description": unique - language map
  • "furtherInformation": multiple - array of objects with properties:
    • "language": language code (optional; omitted e.g. if value is a URL of a photo)
    • "value": the JSON string giving the further information
    • any extra attributes present in the XML: their respective values
  • "rights": unique - language map
  • "created": unique, date-time
  • "modified": multiple - array of date-time
  • "issued": unique - date-time
  • "created": unique - date-time
  • "validityStart": unique - date-time
  • "validityEnd": unique - date-time
  • "version": unique - string (token in XML binding)

Unique human-readable values are represented as a "language map", each object having a two-letter language code as key (the same code as the xml:lang attribute in the XML binding) and a value of the actual string. This means that every string object that can have a language must have a language key.

Multiple values are represented using a single JSON array containing the multiple values.

Using language maps requires an extra restriction compared with the XML binding. For human-readable strings where there is no xml:lang attribute in the XML, the value for the JSON binding will be the value of the default language, which will be given in all cases where there are appropriate strings with no xml:lang attribute.

In addition a LOCstructure could have other optional properties, with keys:

A LOCdefinition may have one additional optional property:

This example shows the use of different languages for the same object value.

JSON example: LOCstructure with some optional additional elements and several LOCdefinitions
{"LOCstructure": {
    "id": "http://www.example.com/abilities/winegrower/1",
    "title": {
            "en": "Wine grower (m/f)",
            "de": "Winzer/Winzerin"
    },
    "description": {
            "en": "Structure of the skills and competences required ......"
    },
    "furtherInformation": [
        {
            "language": "en",
            "value": "http://www.bibb.de/redaktion/ze/en/winzer_e.pdf"
        }
    ],
    "rights": {
            "de": "© Bundesagentur für Arbeit",
            "en": "© Federal Employment Agency",
            "fr": "© L'Agence fédérale pour l'emploi"
    },
    "created": "2010-08-17T00:00:00",
    "version": "2",
    "LOCdefinition": [
        {
            "id": "http://www.example.com/abilities/winegrower/109",
            "description": {
                "en":"Cultivate and tend vines for the purpose of growing grapes"
            }
        },
        {
            "id": "http://www.example.com/abilities/winegrower/111",
            "description": {
                "en":"Make wine using oenological processes"
            }
        },
        {
            "id": "http://www.example.com/abilities/winegrower/113",
            "description": {
                "en":"Make other products from grapes and wine"
            }
        },
        {
            "id": "http://www.example.com/abilities/winegrower/123",
            "description": {
                "en":"Fill, label and pack wine",
                "it": "Riempire, etichettare e impacchettare il vino"
            },
            "furtherInformation": [
                {
                    "language": "en",
                    "value":"\n<div><p>...text...<\/p>\n<\/div>\n",
                },
                {
                    "language": "it",
                    "value": "Riempire, etichettare ........"
                }
            ]
        },
        {
            "id": "http://www.example.com/abilities/winegrower/125",
            "description": {
                "en":"Assess and present wine"
            }
        },
        {
            "id": "http://www.example.com/abilities/winegrower/129",
            "description": {
                "en":"Advise customers"
            }
        }
    ]
}}

LOC associations

The LOCassociations belonging to a LOCstructure are represented in JSON by a single property of the LOCstructure having the key "LOCassociation" and, for its value, an array of objects (the actual LOC associations) with the following properties, all of which are unique, not multiple:

  • "id": optional - IRI
  • "type": mandatory - one of the IRIs for: LOCrel, by, category, level, credit, topic
  • "subject": mandatory - object with properties:
    • "id": mandatory - IRI
    • "label": optional - language map
  • "scheme": mandatory - object with properties:
    • "id": optional - IRI
    • "label": optional - language map
  • "object": mandatory - object with properties:
    • "id": optional - IRI
    • "label": optional - language map

In this example, only one language is given for each string, but the value for each label is still a language map object. More languages may easily be added.

JSON Example of different LOCassociation (by, level, LOCrel, category, topic)
{"LOCstructure": {
    "id": "http://www.example.com/abilities/winegrower/1",
    "language": "en",
    "LOCassociation": [
        {
            "type": "http://purl.org/net/inloc/by",
            "subject": {"id": "http://www.example.com/abilities/winegrower/1"},
            "scheme": {
                "id": "http://purl.org/net/inloc/publisher",
                "label": {"en": "Publisher"}
            },
            "object": {
                "id": "http://www.arbeitsagentur.de/",
                "label": {"en":"Federal Employment Agency"}
            }
        },
        {
            "type": "http://purl.org/net/inloc/by",
            "subject": {"id": "http://www.example.com/abilities/winegrower/1"},
            "scheme": {"id": "http://purl.org/net/inloc/contributor"},
            "object": {"label": {"it":"Chiara Carlino"}}
        },
        {
            "type": "http://purl.org/net/inloc/by",
            "subject": {"id": "http://www.example.com/abilities/winegrower/1"},
            "scheme": {"id": "http://purl.org/net/inloc/contributor"},
            "object": {"label": {"en":"Simon Grant"}}
        },
        {
            "type": "http://purl.org/net/inloc/level",
            "subject": {"id": "http://www.example.com/abilities/winegrower/1"},
            "scheme": {
                "id": "http://www.uis.unesco.org/Education/Pages/international-standard-classification-of-education.aspx",
                "label": {"en":"ISCED 2011"}
            },
            "object": {
                "id": "http://www.uis.unesco.org/Education/ISCED/2011#3",
                "label": {"en":"ISCED level 3"}
            },
            "number": 3
        },
        {
            "type": "http://purl.org/net/inloc/LOCrel",
            "subject": {"id": "http://www.example.com/abilities/winegrower/1"},
            "scheme": {"id": "http://purl.org/net/inloc/hasLOCpart"},
            "object": {"id": "http://www.example.com/abilities/winegrower/109"}
        },
        {
            "type": "http://purl.org/net/inloc/LOCrel",
            "subject": {"id": "http://www.example.com/abilities/winegrower/1"},
            "scheme": {"id": "http://purl.org/net/inloc/hasLOCpart"},
            "object": {"id": "http://www.example.com/abilities/winegrower/111"}
        },
        {
            "type": "http://purl.org/net/inloc/LOCrel",
            "subject": {"id": "http://www.example.com/abilities/winegrower/1"},
            "scheme": {"id": "http://purl.org/net/inloc/hasLOCpart"},
            "object": {"id": "http://www.example.com/abilities/winegrower/113"}
        },
        {
            "type": "http://purl.org/net/inloc/category",
            "subject": {"id": "http://www.example.com/abilities/winegrower/111"},
            "scheme": {
                "id": "http://en.wikipedia.org/wiki/Statistical_Classification_of_Economic_Activities_in_the_European_Community",
                "label": {"en":"NACE"}
            },
            "object": {
                "id": 11.02,
                "label": {"en":"Manufacture of wine from grape"}
            }
        },
        {
            "type": "http://purl.org/net/inloc/category",
            "subject": {"id": "http://www.example.com/abilities/winegrower/111"},
            "scheme": {
                "id": "http://aims.fao.org/aos/agrovoc/c_7644"
            },
            "object": {
                "id": "http://aims.fao.org/aos/agrovoc/c_8405",
                "label": {"en":"Winemaking"}
            }
        },
        {
            "type": "http://purl.org/net/inloc/topic",
            "subject": {"id": "http://www.example.com/abilities/winegrower/115"},
            "scheme": {
                "id": "http://aims.fao.org/aos/agrovoc/c_330919",
                "label": {"en":"AGROVOC objects"}
            },
            "object": {
                "id": "http://aims.fao.org/aos/agrovoc/c_25770",
                "label": {"en":"Winemaking equipment"}
            }
        }
    ],
.....
}

Representing strings and languages in JSON

There are strict rules for representing strings in JSON. See e.g. RFC 4627. In particular, new lines and carriage returns must be escaped, so that a string in JSON cannot be split across several lines. Thus it is not an ideal format for human reading.

For potentially multilingual strings, as illustrated and explained in the examples above, this JSON binding is more restrictive than the XML binding. Every string that could be in more than one language is represented by a language map, in which each string has its language specified.

  • A default language may be specified in the root object.
  • The string to display in any situation should be:
    1. if the language map has only one key:value pair, then that string value; or if there is more than one key:value pair, then
    2. the string corresponding to the desired language; or if this is not present
    3. the string corresponding to the default language, if defined; or
    4. any of the strings in the language map.

Known issues related to the JSON Schema

Recursivity of the JSON Schema

The JSON Schema provided uses $ref to support recursive "LOCstructure"(s) Objects. This functionality remains to be tested.

Validation using JSON Schema

Within the InLOC team, no validation of InLOC JSON Samples using the JSON Schema has been done.
Please report if you test it.

Further reading

Basic JSON information:

JSON Schema:

Other JSON schema implementations to link with inLOC:

XML to JSON conversion: