JSON Topic Maps

JSON Topic Maps 1.0

JSON Topic Maps (JTM) 1.0 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.0 and intends to enable implementers to support JTM for serializing and deserializing topic maps.^[2] This version is superseded by JTM 1.1.

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:

• 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.0". 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:".

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".

6. Examples

6.1. A topic map

{"version":"1.0", "item_type":"topicmap", "topics":[ {"subject_identifiers":["http://psi.topincs.com/movies/dear-wendy"], "names":[ {"value":"Dear Wendy", "type":"si:http://psi.topincs.com/title", "scope":[ "si:http://www.topicmaps.org/xtm/1.0/country.xtm#US", "si:http://www.topicmaps.org/xtm/1.0/country.xtm#DE"]}], "occurrences":[ {"value":"2005", "type":"si:http://psi.topincs.com/publication-year", "datatype":"http://www.w3.org/2001/XMLSchema#gYear"}]}], "associations":[ {"type":"si:http://psi.topicmaps.org/iso13250/model/type-instance", "roles":[ {"player":"si:http://psi.topincs.com/movies/dear-wendy", "type":"si:http://psi.topicmaps.org/iso13250/model/instance"}, {"player":"si:http://psi.topincs.com/movie", "type":"si:http://psi.topicmaps.org/iso13250/model/type"}]}]}

6.2. A topic

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

6.3. An occurrence

{"version":"1.0", "item_type":"occurrence", "parent":["si:http://psi.topincs.com/people/thomas-vinterberg"], "value":"1969-05-19", "datatype":"http://www.w3.org/2001/XMLSchema#date", "type":"si:http://psi.topincs.com/date-of-birth"}