Can keys be scoped to specific DITA maps or projects?

Key Scoping in DITA

In DITA, keys are employed for content reuse. Key scoping is a practice that permits the definition of where a key is accessible. It guarantees that keys are acknowledged solely within designated scopes, like specific DITA maps or projects. This is particularly beneficial for managing intricate documentation projects to avert key name conflicts among distinct topics or maps.


An extensive documentation project is underway for a software product. Keys will be used for cross-referencing shared information, such as the “Installation Guide,” across numerous documents. To forestall key conflicts, keys can be confined to a certain map, for example, denoted as “Software_Docs_Map.”

        <!-- Inside the DITA map "Software_Docs_Map" -->
        <topicref keys="installation_guide_key" href="installation_guide.dita" />

This “installation_guide_key” is now limited in scope to the “Software_Docs_Map.” A reference can be made to it from any topic within this map, ensuring that a key with the same name is not referenced in another context.

        <!-- In a topic within "Software_Docs_Map" -->
          <keyref keyref="installation_guide_key"/>

By deploying scoped keys, key nomenclature can be more effectively regulated, averting clashes, and guaranteeing that keys are employed consistently and precisely within a specific project or DITA map. This is particularly valuable in intricate documentation scenarios.