XTM Fragment Interchange 0.1

1 Introduction

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.

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.

2 The abstract protocol

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.

3 Producing fragments

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.

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.

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.

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.