The OASIS DITA Technical Committee has realized that parts of the DITA 1.2 specification do not unambigiously cover important questions about keys. We offer the following FAQ items in advance of an DITA 1.2 errata:

Given multiple key definitions, how does a processor determine which key definition is effective?

 

A root map and its referenced submaps can contain multiple different definitions for a key. How does a processor determine which definition of the key name is effective?

The DITA 1.2 specification outlines two things that a processor must accomplish:

1. Determine the root map
2. Construct the map tree

A processor cannot perform key resolution until the appropriate resolution context has been defined. To do this, the processor must first determine the root map that establishes the key space. For processors such as the DITA Open Toolkit, the root map is obvious – it is the DITA map to which a transformation is applied – but for authoring tools and component content management systems, the root map is not necessarily obvious; such processors might require that a user explicitly select the root map.

Second, the processor must construct the map tree. The map tree consists of all maps referenced from the root map by @href attributes, all maps referenced from submaps by @href attributes, and so on down the map hierarchy.

Processors must construct the map tree by the document order of the references to the maps in a depth-first traversal of the element tree in each map.

Note:

1. The term document order is formally defined in the XPath Recommendation: http://www.w3.org/TR/xpath/#dt-document-order

2. The term map tree refers to the tree of maps constructed in the manner described here, not the XML element tree for the elements within a single map document.

Overview of key-binding precedence

In general, key-binding precedence follows the principle of “earlier and higher.” This means that the “earliest definition within a DITA map” and the “highest map in the map tree” takes precedence. The intent of this is to ensure the following:

• A key definition located earlier in a single DITA map will override a key definition located later in that DITA map. (Within a single DITA map key precedence is determined by document order.)
• A key definition located in a map referenced closer to the root map will override a key definition located farther away from the root map. (Within the map tree, precedence order is determined by a breadth-first traversal in which processes evaluate all children of a given map before evaluating the descendants of those children.)

For example, to find the effective binding for a given key name, processors will start with the root map of the map tree, look for the first binding in document order within that map, then look at each child map of the root map, and then all the children of the first child of the root map, then all the children of the second child of the root map, and so on until a binding for the key is found.

This design ensures that information architects can reuse maps created by others and override the key definitions used by the original authors and architects. In short, if a team wants to override key definitions in effect in a DITA information set, they can do so by declaring a new key-definition submap at the beginning of the root map. Because the key definitions in such a submap come first after all key definitions in the root map, that submap's key definitions will take precedence over all key definitions except those defined in the root map itself. To override a key definition that is declared in the root map, they must declare a new key definition in the root map; the new key definition must be closer to the beginning of the root map.

Example #1

Consider the following root map:

This map contains three <topicref> elements that define the key name "key-01". The effective definition is the binding to topic-1A.dita, because that is the first key definition in document order. The breadth-first rule only applies to the map tree, not to the tree of elements within the DITA map.

Now, consider the root map with a reference to submap 1 added:

 

If Submap 1 also defines a key name "key-01," that definition cannot be effective. By the breadth-first map tree traversal rule, any definition in the root map takes precedence over definitions in submaps, even though the reference to the submap occurs before any of the key definitions in the root map.

Example #2

Consider a slightly more complicated DITA map with the following characteristics:

• The root map references two submaps.
• One of the submaps references another map.
• The maps contain definitions for two keys–key-01 and key-02–each of which are defined multiple times.

Here is the content of the DITA maps:

Figure: Root map

Figure: Submap-01.ditamap

Figure: Submap-02.ditamap

Figure: Submap-03.ditamap

How are the keys resolved in this example? The processor begins by constructing the following map tree:

When the map tree is traversed in breadth-first order, here is the order in which the DITA maps are encountered:

1. Root map
2. Submap-01
3. Submap-02
4. Submap-03

To determine the effective value of “key-01," the processor traverses the map tree until it encounters a definition. Since the root map has at least one definition for that key, the processor stops there; the key name “key-01” is bound to topic-1A.dita.

To determine the effective value of "key-02," the processor traverses the map tree until it encounters a definition. The root map does not contain a key definition nor does Submap-01. Both Submap-02 and Sub-map 03 contain definitions for key-02, but because Submap 2 comes first in the map tree, the definition that it contains is effective. The keyname key-02 is bound to the topic-2A.dita .

Example #3

A writing team wants to reuse the set of DITA maps outlined in example #2; however, they want to define different values for the key names “key-01” and “key-02. They intend to use root map 2 as their root map

In order to ensure that the two keys are bound to different resources, the information architect must define new values for the keys at a place higher in the map tree than that used in for example #2. The following code samples would product a different effective value for the two keys:

Figure: Root map

Figure: Key-definition.ditamap

Because key-01 is defined in the root map, the information architect must redefine that key at a point earlier in the root map than the existing key definition. Because the first key definition for key-02 exists in submap-01.ditamap, the information architect can redefine key-02.dita in a key definition map that is referenced at the top of the submap.