The XML Topic Maps (XTM) Syntax 1.0

2.1 The topicMap element

The topicMap element is the root element of all XTM topic maps. It acts as a container for the topic map, and can be either the document element of an XML document, or it may be the root of a subtree inside an XML document that contains more than just a single topic map. In both cases, the input to the XTM deserialization process is the subtree contained by the topicMap element.

The topicMap element type is declared as follows:

<!ELEMENT topicMap
   ( topic | association | mergeMap )*
>

<!ATTLIST topicMap
     id              ID        #IMPLIED
     xmlns           CDATA     #FIXED 'http://www.topicmaps.org/xtm/1.0/'
     xmlns:xlink     CDATA     #FIXED 'http://www.w3.org/1999/xlink'
     xml:base        CDATA     #IMPLIED
>

The attributes have the following meanings:

id

A unique identifier for the topic map within the document. Used to refer to the topic map.

xml:base

An attribute used to override the base URI of the document inside the topicMap element, as specified in [XMLBase].

xmlns

This attribute declares the default namespace to be used throughout the XTM document.

Issue (xtm-fixed-attributes):

Attributes declared as #FIXED in the DTD can not be guaranteed to always be present in the XML document as parsed, either because there is no DOCTYPE declaration, or because the parser does not read the DTD. This affects both namespace and XLink parsing, which again affects procedure used to recognize element types.

xmlns:xlink

This attribute declares the xlink namespace prefix to be used throughout the XTM document.

2.2 The topic element

The topic element type is used to create topics, and acts as a container and point of reference for topic information. The child elements of the topic element provide some topic characteristic assignments, as well as other properties, while association roles played by the topic are specified outside the topic element.

The topic element type is declared as follows:

<!ELEMENT topic 
   ( instanceOf*, subjectIdentity?, ( baseName | occurrence )* )
>

<!ATTLIST topic
   id              ID        #REQUIRED
>

The id attribute provides a unique identifier for the topic, which is used to refer to it.

2.3 The subjectIdentity element

The subjectIdentity element type is used to formally declare the subject of the topic created by the parent element, through its child elements.

The subjectIdentity element type is declared as follows:

<!ELEMENT subjectIdentity
   ( resourceRef?, (topicRef | subjectIndicatorRef)* )
>

<!ATTLIST subjectIdentity
   id              ID        #REQUIRED
>

The id attribute is ignored during deserialization.

2.4 The baseName element

The baseName element type is used to add base names to the topic created by the parent topic element. The child elements of the baseName element provide the property values of the base name item.

The baseName element type is declared as follows:

<!ELEMENT baseName
   ( scope?, baseNameString, variant* )
>

<!ATTLIST baseName
   id              ID        #IMPLIED
>

The id attribute provides a unique identifier for the base name, which can be used to refer to it.

2.5 The baseNameString element

The baseNameString element type is used to provide the string that makes up a base name.

The baseNameString element type is declared as follows:

<!ELEMENT baseNameString  ( #PCDATA ) >

<!ATTLIST baseNameString
     id              ID        #IMPLIED
>

The id attribute is ignored during deserialization.

2.6 The variant element

The variant element type is used to create a variant name of a base name, and may also contain other variant names with scopes that are supersets of the scope of that of the containing variant name.

The variant element type is declared as follows:

<!ELEMENT variant
   ( parameters, variantName?, variant* )
>

<!ATTLIST variant
     id              ID        #IMPLIED
>

The id attribute provides a unique identifier for the variant name, which is used to refer to it.

2.7 The variantName element

The variantName element type is used to contain the element that specifies the information resource that is the actual variant name.

The variantName element type is declared as follows:

<!ELEMENT variantName
   ( resourceRef | resourceData )
>

<!ATTLIST variantName
     id              ID        #IMPLIED
>

The id attribute is ignored during deserialization.

2.8 The parameters element

The parameters element type is used to specify the scope of a variant name, in addition to the scope it inherits from its parent base name or variant name.

The parameters element type is declared as follows:

<!ELEMENT parameters
   ( topicRef | subjectIndicatorRef )+
>

<!ATTLIST parameters
     id              ID        #IMPLIED
>

The id attribute is ignored during deserialization.

2.9 The scope element

The scope element type is used throughout XTM to indicate the scope of a topic characteristic assignment.

The scope element type is declared as follows:

<!ELEMENT scope
   ( topicRef | resourceRef | subjectIndicatorRef )+
>

<!ATTLIST scope
     id              ID        #IMPLIED
>

The id attribute is ignored during deserialization.

2.10 The instanceOf element

The instanceOf element type is used throughout XTM to indicate the type of the construct represented by its parent element. The type is always a topic, indicated by the child element.

The instanceOf element type is declared as follows:

<!ELEMENT instanceOf
   ( topicRef | subjectIndicatorRef )
>

<!ATTLIST instanceOf
     id              ID        #IMPLIED
>

The id attribute is ignored during deserialization.

2.11 The occurrence element

The occurrence element type is used to assign an occurrence to a the topic created by the parent element.

The occurrence element type is declared as follows:

<!ELEMENT occurrence
   ( instanceOf?, scope?, ( resourceRef | resourceData ) )
>

<!ATTLIST occurrence
     id              ID        #IMPLIED
>

The id attribute is used to refer to the occurrence.

2.12 The resourceData element

The resourceData element type is used to provide an information resource in the form of a string contained within the XTM document. This information resource may be either a variant name or an occurrence.

The resourceData element type is declared as follows:

<!ELEMENT resourceData
   ( #PCDATA )
>

<!ATTLIST resourceData
     id              ID        #IMPLIED
>

The id attribute is ignored during deserialization.

2.13 The association element

The association element type is used to express associations between topics. The member child elements provide the association role players of the association.

The association element type is declared as follows:

<!ELEMENT association
   ( instanceOf?, scope?, member+ )
>

<!ATTLIST association
     id              ID        #IMPLIED
>

The id attribute is used to refer to the association.

2.14 The member element

The member element type is used to add one or more players of the same association role type to the association created by the association parent element.

The member element type is declared as follows:

<!ELEMENT member
   ( roleSpec?, ( topicRef | resourceRef | subjectIndictorRef )* )
>

<!ATTLIST member
     id              ID        #IMPLIED
>

The id attribute is ignored during deserialization.

2.15 The roleSpec element

The roleSpec element type is used to specify the association role type played by the association player contained in the member parent element.

The roleSpec element type is declared as follows:

<!ELEMENT roleSpec
   ( topicRef | subjectIndicatorRef )
>

<!ATTLIST roleSpec
     id              ID        #IMPLIED
>

The id attribute is ignored during deserialization.

2.16 The topicRef element

The topicRef element type is used throughout XTM to refer to a topic, either within the same XML document or externally. The signficance of the reference depends on the context.

The topicRef element type is declared as follows:

<!ELEMENT topicRef EMPTY>

<!ATTLIST topicRef
     id              ID        #IMPLIED
     xlink:href      CDATA     #REQUIRED
>

The attributes have the following meanings:

id

This attribute is ignored during deserialization.

xlink:href

Contains the URI that is the topic reference.

2.17 The subjectIndicatorRef element

The subjectIndicatorRef element type is used throughout XTM to refer to a subject indicator. The signficance of the reference depends on the context.

The subjectIndicatorRef element type is declared as follows:

<!ELEMENT subjectIndicatorRef EMPTY>

<!ATTLIST subjectIndicatorRef
     id              ID        #IMPLIED
     xlink:href      CDATA     #REQUIRED
>

The attributes have the following meanings:

id

This attribute is ignored during deserialization.

xlink:href

Contains the URI of the subject indicator being referred to.

2.18 The resourceRef element

The resourceRef element type is used throughout XTM to refer to an information resource. The signficance of the reference depends on the context.

The resourceRef element type is declared as follows:

<!ELEMENT resourceRef EMPTY>

<!ATTLIST resourceRef
     id              ID        #IMPLIED
     xlink:href      CDATA     #REQUIRED
>

The attributes have the following meanings:

id

This attribute is ignored during deserialization.

xlink:href

Contains the URI of the information resource being referred to.

2.19 The mergeMap element

The mergeMap element type is used throughout XTM to refer to external topic maps that are to be merged into the topic map that contains the mergeMap element. The child elements of the mergeMap element specify topics to be added to the scopes of all topic characteristic assignments in the topic map to be merged in.

The mergeMap element type is declared as follows:

<!ELEMENT mergeMap
     ( topicRef | resourceRef | subjectIndicatorRef )*
>

<!ATTLIST mergeMap
     id              ID        #IMPLIED
     xlink:type      NMTOKEN   #FIXED 'simple'
     xlink:href      CDATA     #REQUIRED
>

The attributes have the following meanings:

id

This attribute is ignored during deserialization.

xlink:type

This attribute declares the mergeMap element to be a simple XLink element.

xlink:href

This attribute contains the URI that refers to the topic map to be merged into the current topic map. It must refer either to a topicMap element, or to an XTM document.

3.1 Common processing rules

This section defines common processing rules used throughout this specification. These rules are referenced from the sections they apply to.

3.2 The topicMap element

The topicMap element causes a topic map item to be created.

If the topicMap element has an id attribute a locator item is created, with the [notation] property set to "URI" and the [address] property set to the URI of the topicMap element, as defined in 3.1.1 Computing the URI of an element. This locator item is added to the [source locators] property of the topic map item.

If the topicMap element has an xml:base attribute this does not affect the Standard Application Model instance being built, except insofar as it modifies the input XML Information Set.

3.3 The topic element

The topic element causes a topic item to be created and inserted into the [topics] property of the topic map item.

The id attribute causes a locator item to be created, with the [notation] property set to "URI" and the [address] property set to the URI of the topic element, as defined in 3.1.1 Computing the URI of an element. This locator item is added to the [source locators] property of the topic item.

3.4 The subjectIdentity element

The subjectIdentity element has no direct effect on the information set, but changes the interpretation of the child elements. The child elements are processed as follows:

• If there is a resourceRef child, a locator item is produced with the [notation] property set to "URI", and the [address] property set to the absolute form of the URI in the element's xlink:href attribute. The locator item is set as the value of the [subject address] property of the topic item created by the parent topic element. The absolute URI is produced according to the procedure described in 3.1.2 Computing absolute URIs.

• For every subjectIndicatorRef child, a locator item is produced with the [notation] property set to "URI", and the [address] property set to the absolute form of the URI in the element's xlink:href attribute. The locator item is set as the value of the [subject identifiers] property of the topic item created by the parent topic element. The absolute URI is produced according to the procedure described in 3.1.2 Computing absolute URIs.

• For every topicRef child a topic item is produced according to the rules of 3.15 The topicRef element. That topic item is then merged with the topic item created from the parent topic element according to the rules of the Standard Application Model, 4.1 Merging topics.

If the subjectIdentity element has an id attribute that attribute is ignored.

3.5 The baseName element

The baseName element causes a base name item to be created, and added to the [base names] property of the topic item created by the parent topic element.

If the baseName element has an id attribute a locator item is created, with the [notation] property set to "URI" and the [address] property set to the URI of the baseName element, as defined in 3.1.1 Computing the URI of an element. This locator item is added to the [source locators] property of the base name item.

3.6 The baseNameString element

The information items in the [children] property of the baseNameString element are traversed, and for each character information item the Unicode character specified by the [character code] property is added to the [value] property of the base name item created by the parent baseName element.

Ed. Note:
If normalization is required, that must be mentioned here.

If the baseNameString element has an id attribute that attribute is ignored.

3.7 The variant element

The variant element causes a variant item to be created and added to the [variants] property of the base name item created by its baseName ancestor.

If the variant element has an id attribute a locator item is created, with the [notation] property set to "URI" and the [address] property set to the URI of the baseName element, as defined in 3.1.1 Computing the URI of an element. This locator item is added to the [source locators] property of the variant item.

The [scope] property is initialized to the value of the [scope] property of the variant or base name item created by the parent element (which will be either a baseName element or a variant element). (It is implied that the parameters or scope element of the parent has already been processed.)

3.8 The variantName element

The variantName element has no direct effect on the information set being produced, but changes the interpretation of its child element. The child element is processed as follows:

• If the child element is a resourceRef element an absolute URI is produced from the value of its xlink:href attribute, according to the rules of 3.1.2 Computing absolute URIs. From this URI a locator item is produced (with [notation] set to "URI" and [reference] set to the URI) and set as the value of the [resource] property of the new variant item.

• If the child element is a resourceData element the information items in the [children] property of the element item are traversed, and for each character information item the Unicode character specified by the [character code] property is added to the [value] property of the variant item created by the parent variant element.

If the variantName element has an id attribute that attribute is ignored.

3.9 The parameters element

The parameters element has no direct effect on the information set being produced, but changes the interpretation of its child elements. The child elements are processed as follows:

• Each topicRef element causes a topic item to be added to the [scope] property of the variant item created by the parent variant element. The topic item is produced from the topicRef element according to the rules of 3.15 The topicRef element.

• Each subjectIndicatorRef element causes a topic item to be added to the [scope] property of the variant item created by the parent variant element. The topic item is produced from the subjectIndicatorRef element according to the rules of 3.16 The subjectIndicatorRef element.

If the parameters element has an id attribute that attribute is ignored.

3.10 The scope element

The scope element has no direct effect on the information set being produced, but changes the interpretation of its child elements. The child elements are processed as follows:

• Each topicRef element causes a topic item to be added to the [scope] property of the information item created by the parent element. The topic item is produced from the topicRef element according to the rules of 3.15 The topicRef element.

• Each subjectIndicatorRef element causes a topic item to be added to the [scope] property of the information item created by the parent element. The topic item is produced from the subjectIndicatorRef element according to the rules of 3.16 The subjectIndicatorRef element.

• Each resourceRef element causes a topic item to be added to the [scope] property of the information item created by the parent element. The topic item is produced from the resourceRef element according to the rules of 3.17 The resourceRef element.

If the scope element has an id attribute that attribute is ignored.

3.11 The instanceOf element

The instanceOf element has no direct effect on the information set being produced, but changes the interpretation of its child elements. The exact interpretation depends on the parent element of the instanceOf element, however.

Regardless of what parent element the instanceOf element is found in, the child element produces a topic item. If it is a topicRef element the procedure in 3.15 The topicRef element is followed; if it is a subjectIndicatorRef element the procedure in 3.16 The subjectIndicatorRef element is followed.

If the parent element is an occurrence or association elment, the produced topic item is set as the value of the [association type] or [occurrence type] property of the information item produced by the parent element.

If the parent element is a topic element a new association item is created, with two association role items in its [association roles] property. The topic item representing the class-instance association type (described in The Standard Application Model, 5.1 The type-instance relationship) is set as the value of its [association type] property.

The first association role item has its [role type] property set to the topic item representing the class role in the same association (see the section referenced above), while the [role playing topic] property is set to the topic produced by the child element.

The second association role item has its [role type] property set to the topic item representing the instance role in the same association (see the section referenced above), while the [role playing topic] property is set to the topic produced by the parent element (that is, the current topic).

Ed. Note:
This section must be made more formal.

If the instanceOf element has an id attribute that attribute is ignored.

3.12 The occurrence element

The occurrence element causes an occurrence item to be created, and added to the [occurrences] property of the topic item created by the parent topic element.

If the occurrence element has an id attribute a locator item is created, with the [notation] property set to "URI" and the [address] property set to the URI of the baseName element, as defined in 3.1.1 Computing the URI of an element. This locator item is added to the [source locators] property of the occurrence item.

If the occurrence element has a resourceData child element the information items in the [children] property of that element item are traversed, and for each character information item the Unicode character specified by the [character code] property is added to the [value] property of the occurrence item created by the parent occurrence element.

If the occurrence element has a resourceRef child element an absolute URI is produced from the value of its xlink:href attribute, according to the rules of 3.1.2 Computing absolute URIs. From this URI a locator item is produced (with [notation] set to "URI" and [reference] set to the URI) and set as the value of the [resource] property of the new occurrence item.

3.13 The association element

The association element causes an association item to be created, and added to the [association] property of the topic map item.

If the association element has an id attribute a locator item is created, with the [notation] property set to "URI" and the [address] property set to the URI of the baseName element, as defined in 3.1.1 Computing the URI of an element. This locator item is added to the [source locators] property of the association item.

3.14 The member element

The member element does not have any direct impact on the information set being created, but affects the processing of its descendant elements.

For each topicRef child of the member element a topic item is produced according to the rules of 3.15 The topicRef element. An association role item is created, and this topic item is then set as the value of its [role playing topic] property. The association role item is then added to the [association roles] property of the association item.

For each subjectIndicatorRef child of the member element a topic item is produced according to the rules of 3.16 The subjectIndicatorRef element. An association role item is created, and this topic item is then set as the value of its [role playing topic] property. The association role item is then added to the [association roles] property of the association item.

For each resourceRef child of the member element a topic item is produced according to the rules of 3.17 The resourceRef element. An association role item is created, and this topic item is then set as the value of its [role playing topic] property. The association role item is then added to the [association roles] property of the association item.

If the member element has a roleSpec child element, which again has a topicRef element, a topic item is produced according to the rules of 3.15 The topicRef element. That topic item is then set as the value of the [role type] property of each association role item produced above.

If the member element has a roleSpec child element, which again has a subjectIndicatorRef element, a topic item is produced from that element according to the rules of 3.16 The subjectIndicatorRef element. That topic item is then set as the value of the [role type] property of each association role item produced above.

If the member element has an id attribute its value is ignored.

3.15 The topicRef element

The topicRef element always produces a topic item, as described below. How the topic item is used depends on the context in which the topicRef element appears, and is described in the part of this document describing the processing of the topicRef element's parent element.

From the topicRef element a locator item is produced with the [notation] property set to "URI", and the [address] property set to the absolute form of the URI in the element's xlink:href attribute. That absolute form is computed according to the rules in 3.1.2 Computing absolute URIs.

If the topic map processor has not already processed the information resource referred to by the URI (as identified by the part of the URI before the fragment identifier) that information resource is processed.

Ed. Note:
Describe how this processing is done.

If the information set has a topic item whose [subject identifiers] or [source locators] properties contain a locator item equal to the one produced above that topic item is the one produced by this topicRef element.

If no such topic item exists, a topic item is created, and the locator item added to its [source locators] property. That topic item is then the one produced by this topicRef element.

If the topicRef element has an id attribute that attribute is ignored.

3.16 The subjectIndicatorRef element

The subjectIndicatorRef element produces a topic item, as described below. How the topic item is used depends on the context in which the subjectIndicatorRef element appears, and is described in the part of this document describing the processing of the subjectIndicatorRef element's parent element.

From the subjectIndicatorRef element a locator item is produced with the [notation] property set to "URI", and the [address] property set to the absolute form of the URI in the element's xlink:href attribute. That absolute form is computed according to the rules in 3.1.2 Computing absolute URIs.

If the information set has a topic item whose [subject identifiers] or [source locators] properties contain a locator item equal to the one produced above that topic item is the one produced by this subjectIndicatorRef element.

If no such topic item exists, a topic item is created, and the locator item added to its [subject identifiers] property. That topic item is then the one produced by this subjectIndicatorRef element.

If the subjectIndicatorRef element has an id attribute that attribute is ignored.

3.17 The resourceRef element

The resourceRef element produces a topic item, as described below. How the topic item is used depends on the context in which the resourceRef element appears, and is described in the part of this document describing the processing of the resourceRef element's parent element.

From the resourceRef element a locator item is produced with the [notation] property set to "URI", and the [address] property set to the absolute form of the URI in the element's xlink:href attribute. That absolute form is computed according to the rules in 3.1.2 Computing absolute URIs.

If the information set has a topic item whose [subject address] property contains a locator item equal to the one produced above that topic item is the one produced by this resourceRef element.

If no such topic item exists, a topic item is created, and the locator item set as the value of its [subject address] property. That topic item is then the one produced by this resourceRef element.

If the resourceRef element has an id attribute that attribute is ignored.

3.18 The mergeMap element

An absolute URI is produced from the mergeMap element's xlink:href attribute, following the procedure in 3.1.2 Computing absolute URIs. If the information resource referred to by that URI has already been processed nothing further is done. If it has not the procedure below is followed.

First, the information resource referred to is parsed into a representation of the XML Information Set, then one element item from that information set is used to produce a SAM instance, as described in 3 Deserialization. If the URI does not have a fragment identifier the element in the [document element] property of the document information item is chosen as the element item to use as the input to the deserialization process. If the URI does have a fragment identifier the element item in the [owner element] property of the attribute whose [local name] property is set to "id" and whose [normalized value] property has the same value as the fragment identifier is chosen. In both cases, if this element is not a topicMap element an error is reported.

For each topicRef child element of the mergeMap element the topic item produced by the procedure of 3.15 The topicRef element is added to the [scope] property of every information item in the SAM instance produced above.

For each subjectIndicatorRef child element of the mergeMap element the topic item produced by the procedure of 3.16 The subjectIndicatorRef element is added to the [scope] property of every information item in the SAM instance produced above.

For each resourceRef child element of the mergeMap element the topic item produced by the procedure of 3.17 The resourceRef element is added to the [scope] property of every information item in the SAM instance produced above.

Finally, the SAM instance is merged into the current SAM instance, following the procedure described in SAM, 4.3 Merging topic maps. The existing SAM instance is the master topic map, while the new SAM instance is the subordinate topic map.

If the mergeMap element has an id attribute that attribute is ignored, as is the value of its xlink:type attribute.