The @keyscope attribute

The @keyscope attribute consists of one or more space-separated key scope names. Map authors define the boundaries for key scopes by specifying the @keyscope attribute on <map> elements, <topicref> elements, or elements that are specializations of <map> or <topicref>. Such elements, their contents, and any locally-scoped content referenced from within the element, are considered to be part of the scope. Keys defined within a scope are only directly referenceable from within the same scope. They can be referenced from the parent scope using the scope's name, followed by a period, followed by the key name.

Draft comment: robander 19 May 2021
This topic contains a lot of processor / implementation rules and was moved from the langref to the archspec seciton about keys. Need to merge with existing key scope rules to ensure no duplication / no conflicting content.

Update Oct 14 2021: there is now a longer example of the non-intersecting behavior in Example: How key scopes with the same name interact so probably want to remove the simpler example from this page

Draft comment: robander
TO RESOLVE 13 May 2026: No strong opinion here; could remove the example or leave it to have something useful in context. Could also add a related link back/forth between the two topics.

All key scopes are contiguous and non-intersecting. Within a root map, two distinct key scopes with the same name have no relationship with each other aside from that implied by their relative locations in the key scope hierarchy. They do not, for example, share key definitions. The only processing impact of a key scope's names is in defining the prefixes used when contributing qualified key names to the parent scope. For example, consider the following map segment:

<map>
  <topicgroup keyscope="xyz" id="scope1">
    <keydef keys="a" id="def1"/>
    <!-- other topic references -->
  </topicgroup>
  <topicgroup keyscope="xyz" id="scope2">
    <keydef keys="a" id="def2"/>
    <!-- other topic references -->
  </topicgroup>
  <!-- lots of other content -->
</map>

This map creates two distinct scopes that happen to use the same name (xyz). This results in the following:

  • Each <topicgroup> sets a scope of xyz and includes a key a. From outside of those two scopes, references to keyref="xyz.a" (key a within the scope xyz) will always resolve to the first instance of that value, which is in the first <topicgroup>.
  • Within the first <topicgroup>, content uses keyref="a" will resolve to the key in that branch (defined on the element with id="def1").
  • Within the second <topicgroup>, content uses keyref="a" will resolve to the key in that branch (defined on the element with id="def2").