(one of the InLOC Bindings)
This work may be superseded by JSON-LD
We are looking at JSON-LD for the new binding. Please let Simon know if you are interested in helping.
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.
Recursion for child LOCstructures objects is supported. Issues are describe in the "Known issues" section below.
- eCOTOOL D3.5 Competency JSON example Example of an eCOTOOL competency – not tested against the JSON Schema.
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.
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:
- "combinationRules": unique - language map
- "LOCdefinition": multiple - array of LOCdefinition objects
- "LOCassociation": multiple - array of LOCassociation objects
- other sub "LOCstructure": multiple - array of LOCstructure objects
A LOCdefinition may have one additional optional property:
- "primaryStructure": unique - IRI
This example shows the use of different languages for the same object value.
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:
- "scheme": mandatory - object with properties:
- "object": mandatory - object with properties:
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.
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:
- 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
- the string corresponding to the desired language; or if this is not present
- the string corresponding to the default language, if defined; or
- any of the strings in the language map.
The JSON Schema provided uses $ref to support recursive "LOCstructure"(s) Objects. This functionality remains to be tested.
Within the InLOC team, no validation of InLOC JSON Samples using the JSON Schema has been done.
Please report if you test it.
Basic JSON information:
- http://json-ld.org/ JSON-LD: looks like a useful approach
- IETF JSON schema draft v04
- http://jsonschemalint.com/ online service for JSON Schema validation
- http://www.jsonschema.net/ example online service to generate JSON Schema from JSON
Other JSON schema implementations to link with inLOC:
- Europass CV/LP JSON (CV with competency passport and Language portfolio)
- HR-XML Recruiting JSON (CV and Job JSON Profiles with mapping to XML specifications), more information in this pdf: HR-XML Lightweight Recruiting working group, 3 uses cases: Search for Open Positions, Candidate Application, Search for Candidates
- JSON Résumé (CV/résumé profile)
XML to JSON conversion: