Glossary Updates12 new terms added to the glossaries · October 2, 2026, 22:44 CEST
AI TechDocKnowledge

Glossary · Keys and reuse

DITA key

Also known as: keys, keyref, key reference, indirect addressing

In DITA, a key is a name defined in a map (with the @keys attribute) that stands for a resource or a piece of text. Topics and maps refer to the key with @keyref instead of a direct address, and the map that is processed decides what the key resolves to.

  • DITA
  • Reuse

In one sentence

A DITA key is a name defined in a map that stands for a resource or text; topics refer to it with @keyref instead of a direct address.

Example

The key “product-name” resolves to “AP-200” in one map and to “AP-300” in another, so the same safety topic names the right product in each manual.

Explained in context

Context cards connect this term with others to answer one question. Also in British English and German.

How it applies

  • Technical documentation: Keys decouple topics from file locations and variable text. A topic says <ph keyref="product-name"/> or <xref keyref="replace-filter"/>; the map decides what the key resolves to. Changing a file name or a product name means changing one key definition.
  • Key definitions: Keys are defined with @keys on a topicref or on <keydef> (a topicref that is not part of the navigation). A key can point to a resource with @href or carry text in <topicmeta> (for example <keywords><keyword>).
  • Precedence: When the same key is defined more than once, the first definition wins. Key definitions in a parent map take precedence over definitions in submaps, which lets a publication override keys of reused maps.
  • AI and retrieval: Resolve keys before indexing. A chunk that still contains an unresolved keyref loses the product name or the link target the reader would see.

Key vs. content reference

A key is an indirection: it names a resource or a text that the map defines. A content reference copies content. The two combine in the content key reference.

In DITA markup

<!-- in the map -->
<keydef keys="product-name">
  <topicmeta><keywords><keyword>AP-200</keyword></keywords></topicmeta>
</keydef>

<!-- in a topic -->
<p>Switch off the <ph keyref="product-name"/> before cleaning it.</p>