Simple Topic Rolls

Version 1.0

Introduction

This specification defines the simple topic roll format. This can be used to describe a collection of grouped topics in a very simple format without the overhead of a more complicated topic mapping standard such as XTM. In this sense it is intended to be compatible with the ENT 1.0 specification for encoding topics in RSS2.0 feeds and much of the same terminology is used in each.

The keys to it's simplicity are:

It uses the outliner format OPML which has a very simple syntax (one tag and a handful of attributes).
It has a narrow purpose and minimal set of constructs.
OPML is also fairly well supported in outliner tools, which are less specialist than topic mapping tools
It defines topics only to the extent that a specification such as ENT 1.0 might require.

A more complete approach to solving this problem would be use an existing topic map standard such as XTM, XFML or even RDF and we encourage all readers to adopt and use those standards. However for users not comfortable with such advanced and complex standards or in situations which do not justify their complexity we offer topic rolls as a simple, low-cost alternative.

Whilst the topic roll is intended to make creation by non-experts much easier we also appreciate the efforts of domain experts who might wish to work in more advanced formats. In order to allow their work to be leveraged a topic roll can be made to link to another, more sophisticated, document containing further details.

It is intended that users can build an OPML topic roll and that a domain expert could later build a topic map (using XTM for example) and the two can be easily related. This would allow everyone to benefit from the domain experts work, without requiring it to happen in advance.

One final noteworthy feature of the topic roll is the changelog. Because a topic roll is a product of a living system it is subject to frequent change as topics are deleted, renamed, re-classified and so on. For this reason the topic roll provides a changelog mechanism which allows clients to know, unambiguously, what has been changed and act appropriately.

Format

An OPML Topic Roll is created as an OPML outline

Concepts

cloud: The cloud represents a group of topics being published on the web. All classification types & topics exist within the cloud.
classification: The topics in each cloud are classified according to their type.
topic: A descriptive metadatum.
changelog: A pointer to a document describing changes that have been made to the topic roll

Cloud

The cloud represents the overarching grouping of the topics. The cloud is what external resources will refer to.

<!ATTLIST outline
    type		CDATA		#FIXED "cloud"
    serial		CDATA		#IMPLIED
    href		CDATA		#IMPLIED
    fixed		( "true" | "false" )	"false"
    text		CDATA		#IMPLIED
>

type: For a cloud node the type is always cloud.
serial: Contains the serial number of the topic roll. The first version of a topic roll has the serial number 1. For each individual change to the topic roll the serial number will be increased by 1. By this method a client can tell whether it the topic roll has been changed since it was last read.
href: The href attribute can be used to specify a topic map which will back this topic roll.
fixed: If the fixed attribute is true then clients should not expect new topics to be added to this roll.
text: Used to store a description of the cloud.

Classification

The classification represents a related group of topics. Examples of classifications could be person, place, or unit of measurement

<!ATTLIST outline
    type               CDATA         #FIXED "classification"
    id                 CDATA         #REQUIRED
    description        CDATA         #IMPLIED
    text               CDATA         #REQUIRED
>

type: For a classification node the type is always classification.
id: The unqiue id of this classification within the cloud.
description: A description of the classification.
text: Descriptive name of the classification.

Topic

<!ATTLIST outline
    type              CDATA        #FIXED "topic"
    id                CDATA        #REQUIRED
    text              CDATA        #REQUIRED
    href              CDATA        #IMPLIED
>

type: For a topic node the type is always topic.
id: The unique id of the topic.
text: Descriptive name of the topic.
href

ChangeLog

<ATTLIST outline
    type             CDATA         #FIXED "changelog"
    href             CDATA         #IMPLIED
>

type: For a changelog node the type is always changelog.
href: The URL the server advertises for retrieving the changelog. If the URL contains a #SERIAL# template parameter it is an indicator to the client that it supports dynamic changelogs. The client should replace the template parameter with the serial number of it's copy of the topicroll. In return the server will return only those changes since the clients serial number. Otherwise the client should expect to receive a list of all changes to the topicroll. If the client does not support dynamic topic roll is should replace the parameter with the value 0. At present the format of the changelog is not specified and the client will have to deduce it from the returned stream (possibly via the Content-type: header).

Examples

<outline type="cloud" serial="279" href="http://matt.blogs.it/" fixed="false" text="Curiouser and curiouser!">
    <outline type="classification" id="generic" description="The catch-all classification" text="generic">
        <outline type="topic" id="academia" text="academia" href="http://matt.blogs.it/topics/topicsA.html#academia"/>
        <outline type="topic" id="accessability" text="accessability" href="http://matt.blogs.it/topics/topicsA.html#accessability"/>
        <outline type="topic" id="aggregators" text="aggregators" href="http://matt.blogs.it/topics/topicsA.html#aggregators"/>
    </outline>
    <outline type="changelog" href="http://matt.blogs.it/topicrollchanges.cgi?since=#SERIAL#"/>
</outline>

References

ID attribute: Refers to the NAME production in the XML1.0 specification
XML1.0: XML 1.0 (2nd edition)
RDF: Resource Description Framework
XTM: XML Topic Maps
XFML: eXtensible Faceted Markup Language
OPML: Outline Processor Markup Language
[RFC2396]: Uniform Resource Identifiers (URI): Generic Syntax
RSS0.92: RSS Web Syndication Format 0.92
RSS1.0: RDF Site Summary 1.0
RSS2.0: Really Simple Syndication 2.0