What are key scopes in DITA 1.3?

Key scopes in DITA 1.3 refer to a concept that allows for fine-grained control over how keys are processed and resolved within the DITA framework. They provide a means to define different behaviors for keys in various contexts, including maps, topics, and domains, enabling precise customization of key resolution rules. This level of control is valuable in complex documentation scenarios where different content components need to be handled differently based on the context in which they are used.

In DITA 1.3, key scopes allow authors to specify how keys should behave in specific contexts. This is accomplished by associating key definitions with one or more key scopes. Key scopes are used to set conditions, actions, or rules that dictate how keys are resolved. When a key is referenced in content, DITA looks at the key’s associated key scope to determine how it should be processed.

Key Aspects of Key Scopes in DITA 1.3

  • Key Scope Definition: A key scope is defined by associating one or more key definitions with it. Key definitions are typically declared in a map or a topic and are assigned to a specific key scope. This allows the key to inherit the rules and behaviors defined within that scope.
  • Contextual Control: Key scopes provide contextual control over how keys are resolved. Different key scopes can be used to specify different behaviors for the same key in different parts of the documentation. This enables precise control over key behavior in topics, maps, or within specific domains.
  • Key Behavior Rules: Within each key scope, authors can define rules, conditions, or actions that govern key behavior. These rules can include how a key is resolved, whether it is valid within a particular context, and what content should be included or excluded based on the key’s attributes.
  • Customization: Key scopes offer flexibility in customizing key behavior to meet specific documentation requirements. This is particularly useful when handling content variations, conditional processing, or different localization needs.


Suppose you are working on documentation for a software application available in multiple languages and versions. You want to ensure that keys used for referencing user interface elements are resolved correctly based on language and version. Here’s how you can use key scopes in DITA 1.3:

  1. Define Key Scopes: Create distinct key scopes for different contexts, such as “English UI,” “Spanish UI,” “Version 2.0,” and “Version 3.0.”
  2. Associate Keys with Key Scopes: Assign key definitions for UI elements in topics or maps to the appropriate key scopes. For instance, the “OK” button key definition is associated with the “English UI” key scope.
  3. Define Key Behavior Rules: Within each key scope, specify rules and conditions for key resolution. For example, in the “Spanish UI” key scope, set rules to ensure that keys referencing UI elements are resolved to their Spanish translations when generating documentation for the Spanish version of the software.
  4. Conditional Content Inclusion: Use the key scopes to conditionally include or exclude content based on the language and version attributes associated with keys. This ensures that the documentation includes the correct UI element references for each language and software version.