Using keys to address DITA elements

For topic references, image references, and navigation link relationships (<link>, <xref>, and elements that take the @keyref but not the @href attribute), resources can be addressed by key using the @keyref attribute. For content reference relationships, resources can be addressed by key using the @conkeyref attribute.

For references to topics, maps, and non-DITA resources, the value of the @keyref attribute is simply a key name: keyref="topic-key".

For references to non-topic elements within topics and non-topicref elements within maps, the value of the @keyref attribute is a key name, a solidus ("/"), and the ID of the target element: keyref="topic-key/some-element-id".

If both @keyref and @href attributes are specified on an element, the @href value must be used as a fall-back address when the key name is undefined, and should be used as a fall-back address when the key name is defined but the key reference cannot be resolved to a resource. If both @conkeyref and @conref attributes are specified on an element, the @conref value must be used as a fall-back address when the key name is undefined, and should be used as a fall-back address when the key name is defined but the key reference cannot be resolved to a resource.

For example, consider this topic in the document "file.dita":

<topic id="topicid">
<title>Example referenced topic</title>
<body>
<p id="para-01">Some content.</p>
</body>
</topic>

and this key definition:

A keyref of the form "myexample/para-01 resolves to the <p> element in the topic. The key reference would be equivalent, in the context of this map, to the URI reference file.dita#topicid/para-01.

A key reference to a topicref element where the linking element specifies a format value of "ditamap" addresses the topicref element itself as though the topicref element had been addressed by ID. In particular, a topicref with a key reference to another topicref and a format value of "ditamap" is a use of the map branch rooted at the referenced topicref.