OASIS Topic Maps Published Subjects Technical Committee
Pubsubj > Documents > Working documents

Draft examples for inclusion in
Published Subjects - Definitions, Requirements and Examples

Author: Steve Pepper
Date: June 05 2002
Status: Very rough draft

Examples

The purpose of PSIs can be stated (slightly tongue in cheek) as being to make it possible to distinguish apples from oranges. The examples in this section will therefore do exactly that, distinguishing between the fruits 'apple' and 'orange', and between the fruit 'orange' and the colour 'orange'. [FIXME: Haven't done the colour yet.]

1. Examples of published subject identifiers

A PS identifier must be a URI, i.e., it must be either a URL or a URN.

1.1 URLs as published subject identifiers

Any URL that resolves to a subject indicator is considered to conform to this Technical Report.

[recommendation]
In order to facilitate the automated discovery of PSI sets, publishers are recommended as far as possible to use URLs that contain the token 'psi', for example as a component of the hostname or path, thus:

[recommendation]
In order to make PS identifiers easier to remember and use, publishers are advised to consider using human interpretable strings rather than numeric or other values that are not immediately interpretable by humans, provided that this does not otherwise compromise the stability, longevity, acceptability, or usability of the PSI.

All the URLs in the following (non-exhaustive) list abide by this recommendation:

The following URLs do not abide by this recommendation, unless there is some compelling reason for using the non-human interpretable string. An example of such a reason may be that a numeric code has greater stability than the corresponding alphabetic code [FIXME: need to improve formulation]:

1.2 URNs as published subject identifiers

[recommendation]
URNs that conform to registered and approved URN schemes may be used as PS identifiers in conformance with this Technical Report. However, publishers are recommended to consider the implications for usability if there is no well-defined resolution mechanism for the URN scheme.

The following URN could be used to identify the subject 'apple':

2. Examples of published subject indicators

2.1 Subject indicators published in XHTML notation

The following is an example of an XHTML document containing PSIs for the subjects "apple" and "orange":

<!-- this document resides at "http://psi.fruits.org/index.html" -->
<html>
<head>
  <title>Fruits Org's PSI set for fruits</title>
  <meta .../>
  <meta lang="en, fr, jp"/>
  <link rel="topicmap" href="http://psi.fruits.org/fruits.xtm" type="text/xtm">
</head>
<body>
<h1>Fruits Org's PSI set for fruits</h1>
<p>Human readable metadata about the PSI set, including identification
of the publisher and description of scope.</p>

<a name="apple">
  <p><tt>http://psi.fruits.org/#apple</tt></p>
  <h4>English name: apple</h4>
  <p>Some suitable indication of the concept of apple (the fruit).</p>
  <h4>Nôm français: pommes</h4>
  <p>[Indication en français...]</p>
  <h4>[Japanese name: xxxx]</h4>
  <p>[Indication in Japanese...]</p>
</a>

<a name="orange">
  <h4>orange</h4>
  <p><tt>http://psi.fruits.org/#orange</tt></p>
  <p>Some suitable description or definition of the concept of orange (the
  fruit), perhaps with an illustration.</p>
  <h4>Nôm français: orange</h4>
  <p>[Indication en français...]</p>
  <h4>[Japanese name: xxxx]</h4>
  <p>[Indication in Japanese...]</p>
</a>

...

</body>
</html>

2.2 Topic map that using PSIs declared in XHTML

The following example shows an XTM topic map that uses the PSIs declared in the XHTML document shown above:

<!-- this document resides at "http://psi.fruits.org/fruits.xtm" -->
<?xml version="1.0" encoding="iso-8859-1"?>
<topicMap
    xmlns="http://www.topicmaps.org/xtm/1.0/"
    xmlns:xlink="http://www.w3.org/1999/xlink"
>
<topic id="foo">
  <subjectIdentity>
    <subjectIndicatorRef xlink:href="http://psi.fruits.org/#apple"/>
  </subjectIdentity>
  <baseName>
    <baseNameString>apple</baseNameString>
  </baseName>
</topic>
<topic id="bar">
  <subjectIdentity>
    <subjectIndicatorRef xlink:href="http://psi.fruits.org/#orange"/>
  </subjectIdentity>
  <baseName>
    <baseNameString>orange</baseNameString>
  </baseName>
</topic>
</topicMap>

2.3 Subject indicators published in XTM notation

The following is an example of an XTM document containing PSIs for the subject "apple":

<?xml version="1.0" encoding="iso-8859-1"?>
<topicMap
    id="fruits-psiset-tm"
    xmlns="http://www.topicmaps.org/xtm/1.0/"
    xmlns:xlink="http://www.w3.org/1999/xlink"
>
<topic id="apple">
  <subjectIdentity>
    <subjectIndicatorRef
      xlink:href="http://psi.fruits.org/fruits.psi#apple"/>
  </subjectIdentity>
  <baseName>
    <scope>
      <subjectIndicatorRef
        xlink:href="http://www.topicmaps.org/xtm/1.0/language.xtm#en"/>
    </scope>
    <baseNameString>apple</baseNameString>
  </baseName>
  <occurrence>
    <instanceOf>
      <!-- occurrence typed by a PubSubj TC published subject -->
      <subjectIndicatorRef
        xlink:href="http://psi.topicmaps.org/pubsubj/pubsubj.psi#description"/>
    </instanceOf>
    <scope>
      <!-- scope by language English -->
      <subjectIndicatorRef
        xlink:href="http://www.topicmaps.org/xtm/1.0/language.xtm#en"/>
    </scope>
    <resourceData>Some suitable indication of the concept of apple (the
    fruit), perhaps with an illustration.</resourceData>
  </occurrence>
</topic>

...

</topicMap>