JSON Topic Maps

JSON Topic Maps 1.1

JSON Topic Maps (JTM) 1.1 is a notation for the Topic Maps Data Model (TMDM) in JSON. It is meant for machine exchange of topic maps.^[1] This document defines JTM 1.1 and intends to enable implementers to support JTM for serializing and deserializing topic maps.^[2] This version supersedes JTM 1.0. Every valid JTM 1.0 document is also a valid JTM 1.1 document.

1. Terminology

This document uses all Topic Maps terms as defined in the TMDM. Furthermore it uses the following JSON terms:

• object
• array
• string
• null
• name/value pair aka member

2. Topic reference

When a topic is referred to by means of a locator L, the string is to be constructed as follows:

• L is a subject identifier: "si:L"
• L is a subject locator: "sl:L"
• L is an item identifier: "ii:L"

Any such string is called a topic reference.

3. The TMDM Constructs and their members

This section defines which members each construct holds. In addition the type of the value of a member is given. All members are optional unless marked required.

3.1. Topic map

The topic map object contains the following members:

• topics - an array of Topics
• associations - an array of Associations
• item_identifiers - an array of strings
• reifier - a topic reference or null

3.2. Topic

The topic object contains the following members:

• instance_of - an array of topic references
• names - an array of Names
• occurrences - an array of Occurrences
• item_identifiers - an array of strings
• subject_identifiers - an array of strings
• subject_locators - an array of strings

The union of item_identifiers, subject_identifiers, and subject_locators must not be empty.

3.3. Name

The name object contains the following members:

• value - a string required
• type - a topic reference
• scope - an array of topic references
• variants - an array of Variants
• reifier - a topic reference or null
• item_identifiers - an array of strings

3.3. Variant

The variant object contains the following members:

• datatype - a string
• scope - an array of topic references required
• value - a string required
• reifier - a topic reference or null
• item_identifiers - an array of strings

The value of the scope member only contains references to those topics, which are not already contained in the scope of parent name. This follows from the constraint of the TMDM on Variant scope.

3.5. Occurrence

The occurrence object contains the following members:

• datatype - a string
• scope - an array of topic references
• value - a string required
• type - a topic reference required
• reifier - a topic reference or null
• item_identifiers - an array of strings

3.6. Association

The association object contains the following members:

• type - a topic reference required
• scope - an array of topic references
• roles - an non-empty array of Roles required
• reifier - a topic reference or null
• item_identifiers - an array of strings

3.7. Role

The role object contains the following members:

• player - a topic reference required
• type - a topic reference required
• reifier - a topic reference or null
• item_identifiers - an array of strings

4. Serialization

JTM allows the serialization of any topic map item into a document, not only topic maps.^[3]. In any case the document must have a member version with the value "1.1". Furthermore a member item_type must be present. The value must specify the item type (case insensitive): "topicmap", "topic", "name", "variant", "occurrence", "association", or "role" . If an item other than a topic map is serialized, a member parent may be present. The value of the parent member is an array of item identifiers, each prefixed by "ii:". For occurrences and names the parent array may as well contain subject identifiers prefixed by "si:" and subject locators prefixed by "sl:".

4.1 Prefixes

A serializer may choose to shorten an IRI by using a SafeCURIE in the following locations:

• in any topic reference,
• in the member value of Occurrence or Variant for which the member datatype is "http://www.w3.org/2001/XMLSchema#anyURI",
• in the value of a member datatype, and
• in any item of an array which is the value of a member item_identifiers, subject_identifiers, or subject_locators.

Any used prefix must be declared in the member prefixes of the document. Any member of prefixes must have a value of type string. The prefix xsd is bound to the value "http://www.w3.org/2001/XMLSchema#" and must not be bound to any other value. It may be omited from prefixes.

5. Deserialization

Upon deserialization of a JTM document the following rules apply:

1. If the member reifier is not present, the value is null.
2. If the member datatype is not present, the value is "http://www.w3.org/2001/XMLSchema#string".
3. If a member of type array is not present, the value of the member is the empty array.
4. If a member type on a Name is not present, the value is "si:http://psi.topicmaps.org/iso13250/model/topic-name".
5. If the member prefixes is not present, the value is the emtpy object.

A JTM 1.1 conforming deserializer must be able to handle prefixes as desribed in the previous section. It can also read JTM 1.0 documents, thus it should accept JTM documents which version member has the value "1.0".

6. Examples

6.1. A topic map

{"version":"1.1", "prefixes":{"country":"http://www.topicmaps.org/xtm/1.0/country.xtm#", "tns":"http://psi.topincs.com/"}, "item_type":"topicmap", "topics":[ {"subject_identifiers":["[tns:movies/dear-wendy]"], "instance_of":["si:[tns:movie]"], "names":[ {"value":"Dear Wendy", "type":"si:[tns:title]", "scope":[ "si:[country:US]", "si:[country:DE]"]}], "occurrences":[ {"value":"2005", "type":"si:[tns:publication-year]", "datatype":"[xsd:gYear]"}]}], "associations":[ {"type":"si:[tns:director]", "roles":[ {"player":"si:[tns:movies/dear-wendy]", "type":"si:[tns:work]"}, {"player":"si:[tns:people/thomas-vinterberg]", "type":"si:[tns:author]"}]}]}

6.2. A topic

{"version":"1.1", "prefixes":{"tmdm":"http://psi.topicmaps.org/iso13250/model/", "tns":"http://psi.topincs.com/"}, "item_type":"topic", "subject_identifiers":["[tns:people/thomas-vinterberg]"], "instance_of":["si:[tns:person]"], "names":[ {"value":"Thomas Vinterberg", "type":"si:[tmdm:topic-name]"}]}

6.3. An occurrence

{"version":"1.1", "prefixes":{"tns":"http://psi.topincs.com/"}, "item_type":"occurrence", "parent":["si:[tns:people/thomas-vinterberg]"], "value":"1969-05-19", "datatype":"[xsd:date]", "type":"si:[tns:date-of-birth]"}

7. Changes from JTM 1.0