About keyrefs and keydefs

The keyref feature allows you to use indirect addressing in places such as xrefs and related-links.

Instead of referring to a topic directly by its file name, the link is made by means of a symbolic name (keys=”some_name”).

For example, you might make an xref such as the following:
<xref keyref="locale">Import a localized map and its topics</xref>
The link to the target topic is made with the keyref attribute, instead of an href.

The target of this link is established in the map file by inserting the keys attribute into the appropriate topic reference. You can see an example below.

<topicref href="dit1142432953484.xml" keys="locale"/>
Alternatively, you can use a <keydef> element. This allows you, among other things, to make reference to topics outside the scope of the current map, without making them visible in the navigation markup or generating CMS error messages during status changes.
<keydef href="dit1142432953484.xml" keys="locale"/>
Table 1. DITA CMS keyrefs
Icon Description
Unresolved keyref.
Keyref resolved with an href.
Keyref resolved with a keyref.
Keyref resolved with a null link.