DITA Proposed Feature # 40

Keyref architecture

Longer description

The keyref attribute is intended to provide a key-based referencing scheme, with a level of indirection to allow for remapping of targets when content is reused in contexts where the target is unavailable, or a new target needs to be substituted, or several targets need to be collapsed into one.



Use Case

  1. First information architect creates set of content with DITA map. In the DITA map, the information architect identifies a key value associated with each topicref. EG: <topicref href="xyz.dita#mytopic" keys="topicone"/>
  2. Authors create references in the content set (eg conref, keyref, href) using the key to identify the topic, instead of the path plus topicid. EG: <p conref="topicone/mypara"/>, <xref keyref="topicone/mytable"/>, <link keyref="topicone"/>
  3. Second information architect reuses some content from the first content set, but not xyz.dita#mytopic. They remap the key to an equivalent topic (potentially one they create for the purpose). EG: <topicref href="abc.dita#anothertopic" keys="mynewtopic topicone"/>
  4. When the target topic has no equivalent in the information set, the reusing information architect explicitly maps the key to a topicref with no href, eg: <topicref keys="topicone"/>

Would also be nice to allow keyref to topics without an associated key, using their topicid as a default; ie if no key exists for a keyref, look for topicids that match instead; saves a step for the first information architect.

Does require the target topic to have the same internal IDs (eg on <p> or <ph>-level tags), if they are targets; this proposal only supports remapping of the parent topic id, for the sake of simplicity, and for the sake of keeping the map focus on topics rather than elements below the topic level.

Technical Requirements

Add keys attribute to topicref in map

Document keyref syntax: key (or topicid) optionally followed by / and element id; for example,
  • keyref="mytopicid"
  • keyref="key124valuethatmapstomytopic"
  • keyref="mytopicid/myelementid
  • keyref="key124valuethatmapstomytopic/myelementid"

Dcument keys syntax: any number of blank-delimited values, which cannot contain the "/" character

Document expected behavior in language and architectural specs, as follows::
match on topicref with @href, or on topic id
Element with @keyref is turned into link to target identified; if element is empty, text of element is pulled from topicref's title, or topicref's target's title
match on topicref with title but no @href
Element with @keyref is not turned into link. If element is empty, text of element is pulled from topicref's title.
match on topicref with neither title nor @href
Element with @keyref is not turned into link. If element is empty, element is left empty.
no match
Element with @keyref is not turned into link. If element is empty, element is left empty. Warning should be emitted by keyref processor.
Match will be made with the first matching occurrence of a key, based on the sequence of maps processed; if no matches in maps, can then check on topic id matches.


Toolkit will need to include preprocessing pass 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 conrefs can continue being resolved in the editor, even though the conref attribute on its own is no longer enough to locate the content (the conref 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, ie authoring a topic in the context of a map, rather than as isolated chunks.


Major increase in reusability of content. Removes need for file-system-centric workarounds such as conref substitution. Opprtunity 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.

Time Required

2 1 hour meetings to agree on requirements and solution (hoping)

1 day to document