XML Reference Guide

You've probably noticed that the web is full of more information than any reasonable human being can be expected to absorb at any given time. Fortunately, most reasonable human beings don't have to absorb that much information at any given time, but there is still the problem of organizing it so that that reasonable human being can find the information they're trying to absorb.

Many, many different schemes have been tried, of course, and one of them is the idea of "topic maps." Topic maps, as a concept, involves defining "things" as topics, and then creating relationships between those topics. Notice that I didn't say "XML Topic Maps." No, Topic Maps was originally submitted to the ISO as a standard -- ISO 13250 -- based on an SGML language -- HyTime, to be exact. XML Topic Maps are a version of topic maps meant to mesh topic maps with the differences between SGML and XML.

To take a look at building an XML Topic Map, we can take an excerpt from the topic map about free XML software maintained by Lars Marius Garshol. It's huge, so we'll just look at a single product, Xerces-J.

Let's start with Xerces-J itself. In the topic map, we'll define Xerces-J itself, as well as a couple of properties, so we need to define a couple of concepts first. For example:

  <topic id="TMTT_Product">
    <baseName>
      <baseNameString>software product</baseNameString>
    </baseName>
  </topic>

Here we have a basic topic, in this case meant to define the concept of a software product. First, notice that it has an id attribute, so we can refer to it from other elements. Second, we have the baseName. The baseName is what software uses to display the topic. In this case, we've just defined a string, but XTM also enables you to define variants that can be used for sorting or other situations.

When we define Xerces-J, we'll need to talk about several concepts, so we'll put them into the topic map file:

<topicMap xmlns="http://www.topicmaps.org/xtm/1.0/" 
          xmlns:xlink="http://www.w3.org/1999/xlink">

  <topic id="TMOR_Homepage">
    <baseName>
      <baseNameString>home page</baseNameString>
    </baseName>
  </topic>

  <topic id="TMOR_DownloadLocation">
    <baseName>
      <baseNameString>download location</baseNameString>
    </baseName>
  </topic>

  <topic id="TMOR_Description">
    <baseName>
      <baseNameString>description</baseNameString>
    </baseName>
  </topic>

  <topic id="TMTT_Product">
    <baseName>
      <baseNameString>software product</baseNameString>
    </baseName>
  </topic>

</topicMap>

So at this point, we've defined a product, homepage, download location, and description, so we can apply them to Xerces-J itself: First let's define the topic:

<topicMap xmlns="http://www.topicmaps.org/xtm/1.0/" 
          xmlns:xlink="http://www.w3.org/1999/xlink">

...

  <topic id="TMTT_Product">
    <baseName>
      <baseNameString>software product</baseNameString>
    </baseName>
  </topic>

  <topic id="P_Xerces-J">
    <instanceOf>
      <topicRef xlink:href="#TMTT_Product"></topicRef>
    </instanceOf>
    <baseName>
      <baseNameString>Xerces Java</baseNameString>
    </baseName>
  </topic>

</topicMap>

Now, notice that the description of Xerces-J is just a topic element, just like the other topics. In fact, every "thing" in a topic map is defined as a topic. The difference is that in this case, the Xerces-J topic is defined as an "instance" of the product topic, TMTT_Product.

We can also define attributes of Xerces-J, which in the world of topic maps are "occurances":

...
  <topic id="P_Xerces-J">
    <instanceOf>
      <topicRef xlink:href="#TMTT_Product"></topicRef>
      </instanceOf>
    <baseName>
      <baseNameString>Xerces Java</baseNameString>
      </baseName>
    <occurrence>
      <instanceOf>
        <topicRef xlink:href="#TMOR_Homepage"></topicRef>
      </instanceOf>
      <resourceRef xlink:href="http://xml.apache.org/xerces-j/"></resourceRef>
    </occurrence>
    <occurrence>
      <instanceOf>
        <topicRef xlink:href="#TMOR_DownloadLocation"></topicRef>
      </instanceOf>
      <resourceRef xlink:href="http://xml.apache.org/dist/xerces-j/"></resourceRef>
    </occurrence>
    <occurrence>
      <instanceOf>
        <topicRef xlink:href="#TMOR_Description"></topicRef>
      </instanceOf>
      <resourceData>Xerces Java is a validating XML parser with support for the
      DOM level 1 and 2, SAX 1.0 and 2.0, and the XML Schemas final 
      recommendation. Xerces can be invoked through the JAXP API.</resourceData>
    </occurrence>
  </topic>
...

Notice that each occurrance is also an instance of a particular topic, or type of "thing". (This idea of "typing" can actually have a lot more to it, such as the idea of scope and topic types, but I'll leave that for you to discover in the resources.)

This is fine for just defining a topic, but what about defining relationships between topics? In topic maps, a relationship is defined as an "association." Now, before we actually create the association, there's one thing it's important to understand: associations are transitive. That means that with a single statement, I can say that "Xerces-J implements XML Schemas" and "XML Schemas are implemented by Xerces-J".

So, since an association is a "thing," we can create it as a topic:

...
  <topic id="TMTT_Standard">
    <baseName>
      <baseNameString>standard</baseNameString>
    </baseName>
  </topic>

  <topic id="TMAT_StandardImplemented">
    <baseName>
      <baseNameString>implemented standard</baseNameString>
    </baseName>
    <baseName>
      <scope>
        <topicRef xlink:href="#TMTT_Product"></topicRef>
      </scope>
      <baseNameString>implements standard</baseNameString>
    </baseName>
    <baseName>
      <scope>
        <topicRef xlink:href="#TMTT_Standard"></topicRef>
      </scope>
      <baseNameString>implemented by</baseNameString>
    </baseName>
  </topic>

Notice that we have a single baseName, implemented standard, but two other baseNames, implements standard and implemented by, are limited by their scope. In other words, if you are describing the association in the context of a product, you would use "implements standard", whereas if you were talking about the standard itself, you would use "implemented by".

So let's talk about creating the association itself. First we need to create a topic for the standard to be implemented:

...
  <topic id="TMT_Fullname">
    <baseName>
      <baseNameString>full name</baseNameString>
    </baseName>
  </topic>

  <topic id="TMOR_Specification">
    <baseName>
      <baseNameString>specification</baseNameString>
    </baseName>
  </topic>

  <topic id="S_XSchemas">
    <instanceOf>
      <topicRef xlink:href="#TMTT_Standard"></topicRef>
    </instanceOf>
    <baseName>
      <baseNameString>XML schemas</baseNameString>
    </baseName>
    <baseName>
      <scope>
        <topicRef xlink:href="#TMT_Fullname"></topicRef>
      </scope>
      <baseNameString>XML schemas</baseNameString>
    </baseName>
    <occurrence>
      <instanceOf>
        <topicRef xlink:href="#TMOR_Specification"></topicRef>
      </instanceOf>
      <resourceRef xlink:href="http://www.w3.org/TR/xmlschema-1/"></resourceRef>
    </occurrence>
    <occurrence>
      <instanceOf>
        <topicRef xlink:href="#TMOR_Specification"></topicRef>
      </instanceOf>
      <resourceRef xlink:href="http://www.w3.org/TR/xmlschema-2"></resourceRef>
    </occurrence>
    </topic>

</topicMap>

We've already created the association type, so now all we have to do is create the association itself:

...
      <resourceRef xlink:href="http://www.w3.org/TR/xmlschema-2"></resourceRef>
    </occurrence>
  </topic>

  <association>
    <instanceOf>
      <topicRef xlink:href="#TMAT_StandardImplemented"></topicRef>
    </instanceOf>
    <member>
      <roleSpec>
        <topicRef xlink:href="#TMTT_Product"></topicRef>
      </roleSpec>
      <topicRef xlink:href="#P_Xerces-J"></topicRef>
    </member>
    <member>
      <roleSpec>
        <topicRef xlink:href="#TMTT_Standard"></topicRef>
      </roleSpec>
      <topicRef xlink:href="#S_XSchemas"></topicRef>
    </member>
  </association>

</topicMap>

Notice that we haven't actually put any new objects into this association. Instead, we're just referring to previously created objects, or topics. The association itself is an instance of the implemented standard topic, while both members of the association, Xerces-J and XML Schemas, fulfill specific roles, which match up with the scope definitions within the implemented standard topic.

This is, of course, just a brief overview of what you can do with XML Topic Maps, but it should be enough to get you started. Check out the resources for more information on building your own maps and viewing them in topic map software.