DITA Issue # 12007 (draft version #8b, 17 December 2007)

Indirect referencing based on key references and key definitions to increase reusability of content.

This was originally proposed feature #40 (11040).

The current draft is based on an initial draft by Michael Priestley and is the work of an ad hoc subcommittee convened by Michael that includes: Michael, Jeff Ogden, Erik Hennum, Deborah Pickett; Ian Larner; Michael Gannon, Eliot Kimber,  Robert Anderson, and occasionally Don Day.

Longer description

Whenever a topic has a reference to other content, it makes the topic less reusable because of the dependency on the target being still available and still relevant. This proposal introduces a simple key-based redirection scheme that leverages existing attributes and map architectures to provide support for redirectable conrefs, topicrefs, xrefs, links, and other reference elements and attributes. It also provides a simplified architecture for managing variable or volatile content such as product names, which need to be easily swapped out when a topic is reused in new contexts.

Key definitions introduce global identifiers for resources referenced from a map. A key definition defines one or more keys and specifies the resource or resources to which the keys resolve. Map authors define keys using a topicref or topicref specialization that contains the new “keys” attribute. Keys resolve to the resources given as the href value on the key definition topicref element, to content contained within the key definition topicref element, or both.

Topic or map authors include key references on xref, link, topicref, and other reference elements using the keyref attribute. Key references may also be included in the new “conkeyref” attribute. A key reference consists of a key name, optionally followed by a “/” character and an id of a sub-topic element.

During processing key references in topics and maps are resolved using key definitions from maps.

If a key used in a keyref or conkeyref attribute is not defined, the reference is resolved using the href or conref value on the referencing element, if any, as a fallback.




The term “key” and the phrase “key name” are used interchangeably throughout this proposal.

The terms and phrases listed below have the meanings described in RFC 2119 throughout this proposal:

·        must” and the terms "required" or "shall", mean that the definition is an absolute requirement of the specification.

·        must not” and the phrase "shall not", mean that the definition is an absolute prohibition of the specification.

·        should” and the adjective "recommended", mean that there may exist valid reasons in particular circumstances to ignore a particular item, but the full implications must be understood and carefully weighed before choosing a different course.

·        may” and the adjective "optional", mean that an item is truly optional.  One user or vendor may choose to include the item because a particular marketplace requires it or because the user or vendor feels that it enhances the product while another user or vendor may omit the same item. An implementation which does not use or include a particular option must be prepared to interoperate with another implementation which does  include the option, though perhaps with reduced functionality. In the same vein an implementation which does use or include a particular option must be prepared to interoperate with another implementation which does not include the option (except, of course, for the feature the option provides.)

If one of the above terms is not used in the description of a particular feature, the feature is an absolute requirement of the specification.

Use Case 1: Redirect link or xref

  1. Author 1 creates a map that associates keys with each topic, for example <topicref keys="a" href="a1.dita"/>
  2. Author 1 creates topic c.dita that contains a related link to a1.dita - but uses the keyref attribute: <link keyref="a" href="a0.dita"/>
  3. Author 2 reuses c.dita, but wants to redirect the link, so applies a different map with <topicref keys="a" href="a2.dita"/>. The link in c.dita now resolves to a2.dita when author 2 builds it (it continues to resolve to a1.dita when author 1 builds it)
  4. Author 3 also reuses c.dita, but wants the link to point to an external resource, so creates an external-pointing topicref to resolve the key: <topicref keys="a" href="http://www.a..." scope="external"> <topicmeta><linktext>This links to A2</linktext><shortdesc>Because it does.</shortdesc></topicmeta></topicref>. The link in c.dita now resolves to an external URI when author 3 builds it (without affecting how it resolves for the other two reusers).
  5. Author 4 wants to get rid of the link, so creates an explicitly empty topicref to get rid of it: <topicref keys="a"/>. This gets rid of the link for author 4 without affecting the other reusers.
  6. Author 5 wants to turn the link into just plain text (not hypertext): <topicref keys="a"><topicmeta><linktext>This is just text.</linktext></topicmeta></topicref> - for example a citation of a print-only magazine article...
  7. Author 6 reuses c.dita, but does not include a topicref that defines the key “a” in the map.  Topic a0.dita is used as the “fallback” related link.

Note: Should have a warning when an inline xref is removed.

Use case 2: Redirect conref

  1. Author 1 creates a map that associates a key with a topic that contains reusable elements, for example <topicref keys="reuse" href="prodA/reuse.dita"/>
  2. Author 1 uses the key instead of the full href whenever creating conrefs - for example <p conkeyref="reuse/para1"/>
  3. Author 2 wants to reuse author 1's content, but swap in a different set of reusable content. So Author 2 associates the key "reuse" with a different topic: <topicref keys="reuse" href="prodB/mytopic.dita"/>. So now <p conkeyref="reuse/para1"/> will resolve to a paragraph with the id “para1” in prodB/mytopic.dita when author 2 builds the content, while continuing to resolve to the para with the id “para1” in prodA/reuse.dita for author 1.

Note: The reusing author must create a parallel set of elements and ids in the replacement topic - this proposal does not remap the element ids within the topic, only the pointer to the topic container.

Use case 3: Create links from keywords/terms/etc.

  1. Author 1 creates a map that contains glossary entries, and associates keys for each entry: <topicref keys="myterm" href="myterm.dita"/>
  2. Author 1 then uses the keys to create links to the appropriate glossary entry from occurrences of terms in content: <term keyref="myterm">my term</term>.

Use case 4: Swap out variable content

  1. Author 1 creates a map for key words and phrases that tend to change, such as UI labels and product names. The topicrefs do not in this case contain any actual hrefs, just the text that should be used: <topicref keys="prodname"><topicmeta><linktext>My Product</linktext></topicmeta></topicref>
  2. Author 1 then uses the keys to draw text into empty keywords: <keyword keyref="prodname"/>
  3. Author 2 reuses the content but wants to use a different product name, so associates prodname with a different string: <topicref keys="prodname"><topicmeta><linktext>Another Product</linktext></topicmeta></topicref>. The keyword now resolves to "Another Product" for author 2, while continuing to resolve to "My Product" for author 1.

Note: Should generate a warning message when a key reference on an empty element cannot be resolved, resulting in the element effectively being removed.

Use case 5: Splitting/combining targets

  1. Author 1 creates a map in which most branches have the same structure: intro, example, reference. But two branches have only very little content in them, because the product support is only minimal. But in anticipation of future elaboration, author 1 assigns 3 keys to the container under which more topics are expected in the future: <topicref keys="blatoverview blatintro blatexample blatreference" href="blatoverview.dita"/>
  2. Author 2 references blatexample, and in the future when Author 1 moves blatexample into a separate topic, author 2's link remains appropriate and valid and does not need to be reworked.
  3. Author 3 is reusing a bunch of author 1's content, but in a context where blats are not available, and are instead replaced by foobars. So author 3 simply adds the blat keys to their own foobar topicref: <topicref keys="blatoverview blatintro blatexample blatreference foobar" href="foobar.dita"/>

Technical Requirements

1)      Add keys attribute to topicref element in map.

2)      Add keyref attribute to selected elements in topics and maps: data, data-about, longdescref, and navref.

3)      Add the conkeyref attribute to all elements that carry the conref attribute.

4)      Document the keys attribute and key name syntax: The keys attribute value consists of one or more space separated key names. Key names consist of characters that are legal in a URI and must not contain the “{“, “}”, “[“, “]”, “/”, “#”, “?”or space characters. The case of key names is significant.

5)      Include in the DITA Architectural Specification a best practice to reduce the possibility of key name conflicts when topics and maps from one documentation set are reused as part of another documentation set. The best practice encourages, but does not require, all key names to follow a naming convention where key names are qualified using a package or documentation set name. The use of simple or generic key names is discouraged.

The goal is to have packages or documentation sets that are small enough and under the control of a person or a small team so that the use of key names within the package or set can be coordinated by the person or team to avoid name conflicts.

An example of a qualified key name might be “acme.hazard.productname. An example of  simple or generic key names that are likely to result in name conflicts when topics and maps are reused are “platform”, “product” and “productname”.

6)      Document key reference syntax: a key name, optionally followed by the character “/” and a topic element id:

7)      A key reference must be included as the value of the keyref or conkeyref attribute. When an elementid is present as part of a key reference, the id is combined with the resolved key definition value to make the complete reference.

a)      The following elements and attributes may include a key reference:
@keyref on elements that also carry the href attribute: author, data, data-about, image, link, longdescref, lq, publisher, source, topicref, and xref elements;
@keyref on the navref element;
@keyref on elements that do not carry an href attribute: cite, dt, keyword, term, ph, indexterm, index-base, and indextermref; and
@conkeyref on all elements that support the conref attribute.

b)      Specializations based on the elements listed above may also include key references.

c)      The following reference elements and attributes do not support key references:
@href on the synnoteref element (synnoterefs must be same document references),
@longdescref on the image and object elements. @longdescref is deprecated in favor of the new longdescref element (proposal 12050a),
@codebase, @data, @classid, and @archive on the object element.

8)      Add a new element, keydef, to the map group domain as a specialization of topicref (class="+ map/topicref mapgropup-d/keydef"). The specialization is a convenience element similar in purpose to the topichead and topicgroup specializations. The keydef element is used to define keys without any of the other effects that occur when using topicref (no content included in output, no title included in TOC, no linking or other relationships defined).

For the keydef element the keys attribute is required, the toc and print attributes have default values of “no”. The description of the keydef specialization in the DITA specification will make it clear that the keydef element is not the only way that keys are defined (and Michael is free to say I told you so when people don’t read, don’t pay attention, or don’t understand this description).

9)      Update proposal #12013, Conref Range, to allow shortened conrefend attribute values that specify just the topic, just the map, or just the sub-map element portions of the reference with the remaining portion of the reference taken from or implied by the associated conref or conkeyref attribute value.

10)  Expand proposal #12014, “Conref and conditional processing: delayed resolution for use of DITA as a delivery format” to include delayed resolution of key references.

Document required behavior in language and architectural specs, as follows:

11)  A key definition introduces a global identifier for a resource referenced from a map.

12)  Keys are defined in maps and not in topics.

13)  Keys and key references resolve to topics, to collections of topics (ditabase), to maps, to referencable portions of maps, to non-DITA documents, to external URIs, or to XML content contained within a key definition topic reference.

14)  Key references, but not individual keys, may resolve to sub-topic elements.

15)  href attributes in the key definition are resolved relative to the location of the key definition rather than relative to the location of the key reference.

16)  Key definitions are not scoped by the map in which they occur or by the element hierarchy within a map. Key definitions made in maps are visible from other maps including referencing maps at a higher, lower, or the same level in the map hierarchy.

17)  Key definitions in referencing maps take precedence over key definitions in referenced maps.

18)  Key definitions, once made, cannot be redefined.

19)  A key is defined by the first definition found in a breadth-first traversal of the hierarchy of referenced map documents. Thus a key definition in a higher level map takes precedence over key definitions in lower level maps and the first key definition in document order within a single map takes precedence over later key definitions. A duplicate definition within the branch of the map document hierarchy under the defining map is ignored without a warning. A duplicate definition within one map or outside of the branch of the map document hierarchy under the defining map is ignored, possibly with a warning. Note that the phrases “hierarchy of referenced map documents” and “map file hierarchy” mean the hierarchy of map documents or map files and not the element hierarchy within the map documents or files.

20)  Key definitions are part of a global key namespace that is defined by a particular map hierarchy. The order of key definitions and key references relative to one another within the map hierarchy is not significant. Keys do not need to be defined before they are referenced. Forward references are allowed. Keys defined in any map are available for use with key references from all maps and topics..

21)  Key references are not allowed on and will be treated as an error if used with href or conkeyref attributes on topicref elements that reference maps or portions of maps that define keys.

22)  Key references are resolved as follows:

a)      For a matching key definition that includes an href attribute:

The key reference element should be turned into a link to the referenced target; if the key reference element is empty, matching element content, if any, from the key definition element is used.

If there is no matching content from the key definition element, the key reference element remains empty and normal link processing should pull linktext or description (desc) content from the target of the href or use the @navtitle value from the key definition as would normally occur when processing an xref element or specialization.

When @linking="none" is in effect for the key definition, a key reference element such as term or keyword that does not carry an href attribute is not turned into a link, but other processing occurs as usual based on the context of the reference including the potential pulling of link or description text from the reference target.

b)      For a matching key definition with matching content, but without an href attribute:

The key reference element is not turned into a link. If the key reference element is empty, matching element content from the key definition element is used.

c)      For a matching key definition without matching content and without an href attribute:

The key reference element is not turned into a link. If the key reference element is empty, the element remains empty.

d)      When there is no matching key definition:

If there is an href or mapref attribute on the referencing element, the value of the href or mapref attribute is used as the reference and the key reference element is processed as if there were no key reference. Otherwise the key reference element is not turned into a link, and if the element is empty, it remains empty with a warning emitted by the key reference processor.

23)  Matching element content falls into one of two categories:

a)      Matching content for key references contained in keyref or conkeyref attributes on elements which do not also carry an href or mapref attribute (cite, dt, keyword, term, ph, indexterm, index-base, and indextermref and their specializations) is taken from the keyword or term elements within keywords within topicmeta. If more than one keyword or term element is present, the matching content is taken from the first element.

b)      Matching content for key reference elements that carry the keyref attribute, but which do carry an href or mapref attribute (author, data, data-about, image, link, lq, navref, publisher, source, topicref, xref, and their specializations) includes all elements from within the key definition element that are in context within the key reference. Elements that are not in context within the key reference element directly or after generalization are not included or are filtered out.

24)  conrefend attribute values do not include key references. Instead the resolved referenced object of a conkeyref attribute is implied by the object referenced by the conkeyref attribute. The referenced object (file or CMS object, topic, map, or sub-map element) from the key portion of  a conkeyref attribute value overrides and replaces the portion of the conrefend attribute value that refers to the same level object (file or CMS object, topic, map, or sub-map element). The referenced object from the key portion of the conkeyref attribute value is combined with the remaining portion of the conrefend attribute to define the end of the conref range.

25)  The common attributes between a key reference element and a key definition element other than the keys and id attributes are combined in the same way as attributes on source and target conref elements are combined including the special processing for the xml:lang, dir, and translate attributes. There is no special processing associated with either the locktitle or the lockmeta attributes when attributes are combined.

26)  When attributes are combined, the attributes on a key definition element take precedence over the attributes on a key reference element. For a chain of key reference elements the priority for combining attributes is:

1.       1st keys definition element
2.       2nd keys definition element
       . . .
4.       last keys definition element
5.       key reference element

27)  Content from a key reference element and a key definition element is combined following the same procedures that are used for combining metadata between maps and other maps, and between maps and topics. The lockmeta attribute is honored when metadata content is combined.

28)  The combined attributes and content cascade from one map to another or from a map to a topic, but this is controlled by existing rules for cascading which do not change with the use of key references. Note that “cascade” is the new term for what is currently referred to as “inherit” in the DITA 1.0 and 1.1 specifications.

Future Work (post DITA 1.2)

1)      Define a new attribute for use on topicref that would provide a way to define or restrict the roles the topicref element is playing. The goal is to provide a way to say that the topicref is being used to define keys, but not to reference content or define relationships or other combinations in a way that is more scalable than just adding a new “keydef='{yes | no | only}' attribute to supplement the existing print and toc attributes. Use of an attribute similar to @class and @domains named “usage” that would have a space separated list of tokens (content, relationships, properties, …) declared as a default value in DTDs and schemas, but not generally for use in document instances, was discussed.

2)      Consider adding a scoping mechanism for use with key definitions and possibly other aspects of DITA based on the map hierarchy or the combined element hierarchy within a set of maps.

3)      Consider allowing subsequent key definitions within the same map or within peer maps to override previous key definitions, probably as part of some hierarchal scope, and probably in a fashion that is the same as or similar to override mechanisms to be developed for other features such as ditaval.

4)      Consider providing a mechanism that would allow map authors to override references in maps and topics even if references in the maps and topics were not authored using key references or with indirect referencing in mind.


The DITA Open Toolkit and other output processing implementations will need to include processing to turn key references into file/topic references for HTML or other output.

Usability requirements on editors to support key-based references, for example so that conref content for conkeyrefs that use key references can continue to be displayed  by an editor, even though the conkeyref attribute on its own does not provide enough information to locate the content (the conkeyref must be interpreted in the context of a map file that associates the target key with a particular topic).

This puts a further premium on supporting map-based authoring, i.e., authoring a topic in the context of a map, rather than as isolated chunks.

Increased complexity for both authors and implementers, particularly with the continued overloading of the topicref element.


A major increase in reusability of content.

Removes need for file-system-centric workarounds such as conref substitution.

Opportunity for improved compatibility between different content management systems, and between CMSs and other systems such as file systems, dynamic web publishing systems, databases, etc. - each of which could use their own key scheme and just externalize it as a map file for the keyed content, as well as remapping keys to the preferred linking or retrieval mechanism at runtime.

Support for Issue #12031, Controlled Values / Taxonomies.

Time Required

Several meetings to agree on requirements.

Two days to document.

Time to implement changes to DTDs and schemas.

Time to implement changes to DITA Open Toolkit and other output processors.