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

Glossary · Keys and reuse

DITA key scope

Also known as: keyscope, key scopes, scoped keys

In DITA 1.3, a key scope is a part of a map, declared with the @keyscope attribute, within which key definitions and key references are resolved separately from the rest of the map. The same key can therefore have different values in different branches of one publication.

  • DITA
  • Reuse
  • New in DITA 1.3

In one sentence

A DITA 1.3 key scope (@keyscope) lets the same key resolve to different values in different branches of one map.

Example

A combined manual for two air purifiers uses the key scopes “ap200” and “ap300”, so the shared safety topic shows the right product name in each part.

How it applies

  • Technical documentation: Before DITA 1.3, a key had exactly one value per root map. Key scopes, new in DITA 1.3, allow one publication to combine several products: each product's submap gets its own scope, and the same key (“product-name”) resolves differently in each.
  • Precedence: Key definitions in a parent scope take precedence over those in a child scope, so a publication can still override keys for all its parts.
  • Qualified names: From outside a scope, a key is addressed with the scope name as prefix — ap200.product-name — which allows one product's section to refer to a topic in another's.
  • Cross-deliverable linking: Key scopes on a peer map reference (scope="peer" with @keyscope) let one publication link to topics in another publication — also new in DITA 1.3.
  • AI and retrieval: When a topic is published in several scopes, it produces several versions of resolved text. Index each resolved version with its scope, not the source file, so an answer about the AP-300 is not given from the AP-200 variant.

Key scope vs. branch filtering

Key scopes change what keys resolve to within a branch of a map. Branch filtering changes which content is included in a branch. Both are new in DITA 1.3 and are often used together.

In DITA markup

<map>
  <topicgroup keyscope="ap200">
    <keydef keys="product-name"><topicmeta><keywords><keyword>AP-200</keyword></keywords></topicmeta></keydef>
    <topicref href="safety.dita"/>
  </topicgroup>
  <topicgroup keyscope="ap300">
    <keydef keys="product-name"><topicmeta><keywords><keyword>AP-300</keyword></keywords></topicmeta></keydef>
    <topicref href="safety.dita"/>
  </topicgroup>
</map>