This document defines a syntax for interchange of topic map fragments, based on an abstract protocol. The syntax here defined is a subset of the XTM 1.0 syntax with certain additional conventions that make it work effectively as a fragment interchange format. The format can be parsed by XTM 1.0 parsers.
This is $Revision: 1.1 $.
A topic map is a collection of information organized around binding points (topics), which makes topic map information amenable to interchange in fragments. Much has been said about using topic maps for "global knowledge interchange", and a fragment syntax is a first step towards realizing such a vision. Using it, topic map information can be exchanged in fragments, more fragments requested as needed, and the parts joined into a whole on the receiving end.
The syntax is described using a notion of an abstract protocol where clients may request information from a server. The syntax is then described as a serialization from an instance of the Standard Application Model [SAM] to the XTM Fragment syntax. The XTM Fragment syntax is simply a subset of the XTM 1.0 syntax, with the same interpretation, and so the deserialization of XTM Fragments is that described in [XTM]. When deserializing XTM Fragments, however, topicRef elements that point to locations outside the XTM Fragment instance must never be followed.
Does XTM 1.0 allow us to not follow such references?
Another necessary step towards realizing the vision of "global knowledge interchange" is a "Remote Topic Protocol" (RTP). This fragment syntax is explicitly designed to enable its use within such a protocol. A separate note describing the protocol may follow as time allows.
This document describes a request-response protocol with no specific syntax for the client-server interaction, hence its designation as abstract. The protocol has no notion of sessions or state across request-response pairs, and so can easily be adapted to different transport protocols, including HTTP.
The protocol has only a single request: get topic information, where the client provides a number of URIs, each one of which is identified as either a source locator, a subject identifier, or a subject address. This list of URIs identifies the topics the client would like to see included in the fragment.
The server takes a SAM model instance (effectively a topic map), and using the URIs sent by the client produces an XTM Fragment instance, as described in 3 Producing fragments. This document does not concern itself with how the server decides which topic map the request refers to. It is assumed that in translating the abstract protocol into a concrete implementation implementors will devise some suitable solution.
Implementations may choose what character encoding to produce the XTM Fragment in, so long as they follow the rules given by [XML] for indicating the encoding chosen. The UTF-8 encoding is recommended, being both readable in tools which do not support UTF-8 and at the same time able to support all Unicode characters.
The document element of XTM Fragment documents is the topicMap element, on which the attributes defined as fixed in [XTM] must be set.
The contents of that element are produced by iterating over the URIs
in the list of input URIs. For each URI, a topic element is
produced from the SAM instance by looking up the topic item which has
a locator item with [notation] set to
"URI" and the given
URI in its [reference] property in:
its [source locators] property, if the URI is a source locator,
its [subject identifiers] property, if the URI is a subject identifier, or
its [subject address] property, if the URI is a subject address.
How to preserve reification relationships?
For the topic item a topic element is then produced. The elements are given an id attribute whose value may be anything so long as it matches the Name production and the same topic always gets the same value in every response. This value is not used in any way, and the purpose of this is solely to conform to the XTM 1.0 syntax and avoid causing an explosion of source locators for the same topics.
Can we get into problems if clients start referring to the topic by a URI derived from its id attribute? This may not be a source locator on the server side.
If the topic item has at least one locator item in one of the [subject identifiers], [subject address], or [source locators] properties, a subjectIdentity property is produced. Its contents are produced as follows:
For each locator item in the [subject identifiers] property a subjectIndicatorRef element is output, with its xlink:href attribute set to the value in the locator item's [reference] property.
If the [subject address] property has a locator as its value, a resourceRef element is output, with its xlink:href attribute set to the value in the locator item's [reference] property.
For each locator item in the [source locators] property a topicRef element is output, with its xlink:href attribute set to the value in the locator item's [reference] property.
What about non-URI locators? Are they just ignored?
For each base name item in the topic item's [base names] property, a baseName element is produced. Section 3.1 Producing scope elements describes how to add a scope element, if required. A baseNameString element is then output, containing the string in the base name item's [value] property.
For each variant item in the base name item's [variants] property, a variant element is output. Section 3.1 Producing scope elements describes how to add a parameters element, if required. A variantName element is then output, and inside it either a resourceData element containing the [value] property's value (if it is not null) or a resourceRef element with the xlink:href attribute set to the value of the [reference] property of the locator item in the [resource] property (if it is not null).
For each occurrence item in the topic item's [occurrences] property, an occurrence element is produced. If the [occurrence type] property contains a topic item, an instanceOf element is produced, containing a reference to it. (Section 3.2 Producing references to topics describes how to reference topics.) Section 3.1 Producing scope elements describes when and how to add a scope element.
For each association role item in the topic item's [roles] property, an association element is produced after the topic element, provided the association item has not already been output. If the [association type] property contains a topic item, a reference to it is produced inside an instanceOf element. A scope element is then added, if needed.
Finally, for each association role item in the [roles] property, a member element is output. That element must contain a roleSpec element with a reference to the topic item in the [role type] property and a reference to the topic in the [role playing topic] property.
This approach can easily cause associations to be duplicated. This need not be critical, but is better if avoided. What to do?
A scope element is output if the parent item has a non-empty set in its [scope] property (except for variant items, in which case a parameters element is output instead). For each topic item in the [scope] property a topic reference is then output as described in the following section.
To produce a reference to a topic item, follow this procedure:
If the [subject address] property contains a locator item, output a resourceRef element with the xlink:href attribute set to the value of the locator item's [reference] property.
If the [subject identifiers] property contains at least one locator item, output a resourceRef element with the xlink:href attribute set to the value of a locator item's [reference] property. Implementations are not required to apply any particular algorithm to pick a locator item to use, but are recommended to always pick the same locator item when referring to the same topic item.
If the [source locators] property contains at least one locator item, output a topicRef element with the xlink:href attribute set to the value of a locator item's [reference] property. Implementations are not required to apply any particular algorithm to pick a locator item to use, but are recommended to always pick the same locator item when referring to the same topic item.
For topic items which have no locators items in any of these properties implementations must add a unique locator to the [source locators] property of the topic item before applying the above algorithm.