TMIP, Topic Map Interaction Protocol 0.3, Specification

TMIP is a protocol which allows clients to access content from a TM store. It works under the assumption that the store contains topic map instances which are either accessed as a whole or - using TMQL as selection mechanism - in part. The protocol does not assume anything about the storage itself. Maps may be deserialized in memory, may be serialized in textual form using some format, or may even be virtual, i.e. only wrappers around non-Topic Map resources.

TMIP is to satisfy the following requirements:

It achieves most of this by reusing the mechanics of the HTTP[HTTP] protocol and extending it by a minimum amount of headers and MIME types. It uses only the predefined HTTP methods, GET, POST, PUT and OPTIONS.

Consequently, this specification depends on the following standards:

and adheres to the Web Architecture[WWWA]. The following documents are only relevant for optional features:

The protocol is assumed to work between a client and a server. The client is always the initiating party. It is outside the scope how the client learns which information can be found on which server.

A server is the connection endpoint to a map store. That stores topic maps (and maybe other information objects) in a hierarchical namespace (section the section called “Addressing Resources”). Topic Map stores are not constrained in the form (representation) of these maps. They can be deserialized in memory, disk or deserialized in any binary or text representation.

Not in the scope of the protocol is authentication. HTTP itself has several authentication mechanisms and implementations may - on top of TMIP - implement their own authentication mechanism (using cookies). Also not in the scope is confidentiality as that is covered by HTTPS.

Following a REST-approach, TMIP is context-free, i.e. subsequent requests have no correlation whatsover. This implies that it is not possible with TMIP itself to implement transactions. Implementations, though, are free to add this facility (e.g. using WebDAV[WebDAV]).

All resources are addressed using a URI following the rules in URL[URL] with the additional limitation that the path component follows the grammar:

  path              -> map-selector [ tmql-path-postfix ] 

  map-selector      -> '/' [ /\w+/ map-selector ]

  tmql-path-postfix -> string according TMQL:7.2
      

Examples:

  /xxx/yyy/zzz/            # addresses a whole map

  /xxx/yyy/zzz//aaa/       # addresses all things of type aaa in above map
      

The structure of the map selector implies a hierarchical organisation on the server side. The top-level location has the selector / and is called the root of the map store.

All messages between client and server follow the structure given by the HTTP protocol. The body of the messages may carry payload; that content type is then specified in the Content-Type header. Relevant for the protocol are:

The following MIME types are relevant to the protocol:

The default XML encoding for tuple sequences is defined via RelaxNG[RelaxNG]

default namespace = "http://astma.it.bond.edu.au/ns/tmip/1.0/ts/"
namespace xtm     = "http://www.topicmaps.org/xtm/1.0/"

start   = seq

seq     = element   seq { ordered?, t* }
ordered = attribute ordered { (yes|no) "no" }
t       = element   t   { (id | s | i) }
id      = element   id  { text }
s       = element   s   { text }
i       = element   i   { xtm:* }
      

An <i> element can contain any XTM element according to XTM[XTM].

Example:

<seq xmlns="http://astma.it.bond.edu.au/ns/tmip/1.0/ts/">
   <t>
     <id>firefox</id>....
     <s>Firefox, the Browser</s>
     <i>
        <xtm:topic id="firefox" xmlns:xtm="....">
         <!-- ... -->
        </xtm:topic>
     </i>
   </t>
   <t>
     <id>Mozilla</id>....
     <s>Mozilla</s>
     <i>
        <xtm:topic id="mozilla" xmlns:xtm="....">
         <!-- ... -->
        </xtm:topic>
     </i>
   </t>
</seq>
      

TMIP makes use only of the methods GET, OPTIONS, PUT, DELETE and POST. These methods are invoked on the resource identified by the message URI. The message URI is either one which addresses a whole map; consequently the invocation of the method applies to that map. Optionally, the URI may also contain a TMQL path expression additionally to the map location.

All XML content in request bodies must validate against the appropriate schema, or a response code RC_NOT_ACCEPTABLE will be returned by the server. Specifically, application/x-tmql-sequence+xml must validate against the rules in section the section called “Tuple Sequence Encoding” and XTM content must validate against the XTM 1.1 schema[XTM].

As the server is only the gateway to the actual map store, accesses into this store can fail. If this is the case, the server will respond with RC_INTERNAL_ERROR messages.

In the following we list all possible request message scenarios and the appropriate server responses. Any combination not mentioned below is errorenous and will result in a RC_BAD_REQUEST response. Below, a value null for a header or the body means that it is completely ignored by a server.

All messages with a body MUST have a Content-Length: header.

REST is cool.

Fielding02 (phd-thesis)
bn: Architectural Styles and the Design of Network-based Software Architectures, PhD.
in: University of California, Irvine, 2002
in (author): Fielding R.
oc: http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm

ArtUNIX03 (book)
bn: The Art of Unix Programming
in (author): Eric Steven Raymond
oc: http://www.faqs.org/docs/artu/

HTTP (rfc)
bn: RFC 2616, HTTP
in (author): R. Fielding, J. Gettys, H. Frystyk, et.al
oc: http://www.faqs.org/rfcs/rfc2616.html

MIME

URI

URL

WebDAV

Storable

RelaxNG


LTM (specification)
bn: LTM, The Linear Topic Map Notation, Lars Marius Garshol, Ontopia A/S
oc: http://www.ontopia.net/download/ltm.html

AsTMa= (specification)
bn: AsTMa= Language Definition, Robert Barta, TechReport, Bond University
oc: http://astma.it.bond.edu.au/astma=-spec-xtm.dbk

TMQL (standards-draft)
bn: Topic Maps Query Language, Working Draft, ISO/IEC JTC1/SC34
in (editors): Lars Marius Garshol, Robert Barta
oc: http://www.isotopicmaps.org/tmql/spec.html

WWWA
bn: WWWA, Architecture of the World Wide Web, Volume One
in (editors): Ian Jacobs, Norman Walsh
oc: http://www.w3.org/TR/webarch/

XTM (standard)
bn @short: XTM 1.1
bn: Topic Maps - XML Syntax, JTC1 / SC34
in (editors): Lars Marius Garshol, Graham Moore
oc: http://www.isotopicmaps.org/sam/sam-xtm/