Topic Maps Remote Access Protocol

Definition and introduction

Author:Graham Moore
Affiliation:Ontopia A/S
Date:$Date: 2004/04/23 08:51:35 $
Version:Version 0.2 ($Revision: 1.1 $)

Abstract

This technical report defines version 0.2 of a service for communicating between Topic Maps applications.

This service defines a small set of operations that among other things enables the construction of integrated topic map portals. The operations defined address several different kinds of integration: link integration, presentation integration, and semantic structure integration. The service is not defined with any specific domain in mind but instead attempts to provide behaviour that will be relevant to a large class of Topic Maps-based integration problems.

Note: All service operations are defined in a RESTful fashion. No justification of this approach is given here.

Other contributors to this document: Arnar Lundesgaard, Lars Marius Garshol, Steve Pepper

Service Definition

This section defines the different operations of the TMRAP service in enough detail to allow implementations to be based upon it. Examples are given along with each operation to aid understanding of the semantics.

1. Topic Page

Description

Topic Map driven portals often promote the concept of one page one subject/topic. This page is not necessarily an occurrence of the topic in question but a rendition of it (this rendition is most likely generated from information in the topic map and it may display links to other topics, etc). The ability to ask such a portal about the 'topic page' for a given topic allows integrating applications to preserve the branding and look and feel of the original portal while still pulling in content relevant to a given topic.

Operation


  getTopicMainPage(TopicIdentifier[] ti)
    => XLink reference_to_main_page_in_portal;

REST Service structure for invocation


  [some service]/topic-page?[subject identity parameters]

  Allowed values in [semantuc identity parameters] are of the form
  indicator=<some identifier>
  source=<some identifier>
  subject=<some identifier>

The parameters 'indicator' and 'source' can be repeated, i.e to allow several indicators, but only one subject parameter is allowed (related to Subject Locator issus in TMDM).

[some service] is left undefined as different deployments of the service will want to change this.

Return structure


  <topic-page
  xmlns:xlink="http://www.w3.org/1999/xlink"
  xlink:type="simple"
  xlink:href="[Reference to the topic page within the portal]"
  xlink:title="[optional - text]">
  [optional - text]
  </topic-page>

Example

Request:

  GET http://www.opera.org/topic-page?indicator=http://psi.opera.net/composers/puccini

Response:

  <topic-page
  xmlns:xlink="http://www.w3.org/1999/xlink"
  xlink:type="simple"
  xlink:href="http://www.opera.org/showtopic?id=T45"
  xlink:title="Puccini">
  Puccini at opera.org
  </topic-page>

2. Topic Occurrences

Description

Topics may have occurrences (references to relevant resources). This information is useful in portal integrations as it allows the integrating portal to include references to other resources relevant to a given topic without including the topic page and without having to get and process a complete XTM fragment.

Operation


  getTopicOccurrences(TopicIdentifier[] ti)
    => XLink references_to_occurrence_resources;

REST Service structure for invocation


  [some service]/occurrences?[subject identity parameters]

Return structure

The structure returned by this request:


  <topic-occurrences>
  <occurrence
  xmlns:xlink="http://www.w3.org/1999/xlink"
  xlink:type="simple"
  xlink:role="[optional - xtm topic reference for occurrence]"
  xlink:href="[Reference occurrence resource]"
  xlink:title="[optional - display name of occurrence type]">
  [optional - display name of occurrence type]
  </occurrence>
  </topic-occurrences>

Example

Request:

  GET http://www.opera.org/tmrap/occurrences?indicator=http://psi.opera.net/composers/puccini

Response:

  <topic-occurrences>
  <occurrence
  xmlns:xlink="http://www.w3.org/1999/xlink"
  xlink:type="simple"
  xlink:role="http://www.opera.org/tmrap/topics/[@"T45"]/xtm"
  xlink:href="http://www.world-of-opera.com/puccini"
  xlink:title="web resource">
  web resource
  </occurrence>

  <occurrence
  xmlns:xlink="http://www.w3.org/1999/xlink"
  xlink:type="simple"
  xlink:role="http://www.opera.org/tmrap/topics/[@"T47"]/xtm"
  xlink:href="http://www.world-of-opera.com/puccini/sounds/n1.wav"
  xlink:title="sound clip">
  sound clip
  </occurrence>
  </topic-occurrences>

3. Topic Map Portal Services

Description

To dynamically integrate new topic map sources there is a need for some kind of lookup service from which existing sources can be found. We expect this capability to mature into a fairly sophisticated pattern but for this initial activity we assume that any semantic portal service can provide a list of other portals that may have interesting information about a particular domain. We do not say in how the portal gains this information at this stage but the basic capability to locate portal services is useful. This request provides a simple way to bootstrap the protocol in initial prototypes.

Operation


  getTopicMapPortalServices() => XLink reference_to_portal_services;

REST Service structure for invocation


  [some service]/topicmapportalservices

Return structure

The structure returned by this request:


  <topic-map-services>
  <service
  xmlns:xlink="http://www.w3.org/1999/xlink"
  xlink:type="simple"
  xlink:href="[portal uri]"
  xlink:title="[optional - text]">
  [optional - text]
  </service>
  </topic-map-services>

Example


Request:

  GET http://www.opera.org/tmrap/topicmapportalservices

Response:

  <topic-map-services>
  <service
  xmlns:xlink="http://www.w3.org/1999/xlink"
  xlink:type="simple"
  xlink:href="http://www.opera.org/tmrap"
  xlink:title="opera portal">
  opera portal
  </service>

  <service
  xmlns:xlink="http://www.w3.org/1999/xlink"
  xlink:type="simple"
  xlink:href="http://www.edu.no/portal-service"
  xlink:title="arts education portal">
  arts education portal
  </service>
  </topic-map-services>

4. Topic XTM

Description

Although presented last it is this request that has the largest scope of usefulness and the most complexity. It basically provides a mechanism for a remote client to retrieve from a topicmap portal a fragment of XTM for a given topic. Issue with this are in the area of how much information should be returned? For this prototype we proposed that the topic and all one step topic references are return as a single XTM fragment. That all associations where the topic plays a role are also included along with their typing topics. The algorithm is explained below in detail.

Operation


  getTopicXTM(TopicIdentifier[] ti)
    => XTMFragment xtm_representation_of_part_of_topic_map;

REST Service structure for invocation


  [some service]/xtm-fragment?[subject identity parameters]

Return structure

The return structure will be a topic map fragment in the form of a valid XTM instance. This version of the TMRAP specification does not constrain the exact content of this fragment in any way. In other words, the portal application is free to return whatever it likes, in addition to the topic specified in the request.

Additional work needs to be done to establish a more flexible and predictable way of specifying what kind of fragment the requestor would like to be returned. This is expected to be closely related to the work on TMQL.

References to topics and other constructs that are not included within the xtm fragment should take the form of topicRef elements where the value of the xlink:href attribute is a reference back to the service that generated this XTM fragment. e.g. http://www.opera.org/tmrap/xtm-fragment?source=[source locator]. This will allow remote applications to make subsequent requests to gather more information should they so wish.

The structure returned by this request:


  A valid XTM instance.

Example


Request:

  GET http://www.opera.org/tmrap/xtm-fragment?indicator=http://psi.opera.net/composers/puccini

Response:

  A valid XTM instance.

Future Directions

This protocol has been rapidly designed and implemented to facilitate further discussion regarding what it means to integrate topic map portals – or Topic Maps applications in general. It is expected that the outcomes of these discussions will change the shape of this protocol. In particular it is expected that additional services based on TMQL will be introduced in the near future.