Referencing a key with the @keyref attribute

The @keyref attribute provides an indirect, late-bound reference to topics, to collections of topics (ditabase), to maps, to referenceable portions of maps, to non-DITA documents, to external URIs, or to XML content contained within a key definition topic reference. When the DITA content is processed, the key references are resolved using key definitions from DITA maps.

Draft comment: robander
This topic moved from the arch spec section. It needs editing for
  • Overlap with existing content - likely needs to merge, definitely remove duplication
  • This topic uses a key and the langRef links to it from the definition for @keyref, so if this topic goes away, be sure to update that keyref
Draft comment: robander
TO RESOLVE 13 May 2026: Looking at the TOC, it's probably fine to keep a topic here about the keyref attribute, but maybe we should update the title to "About the..." or "Using the..." or "Referencing a key name with the..."? Same goes for the topic a bit further down, "The keyscope attribute"

Also, based on discussion at the TC meeting May 12 2026, assuming we stick with the conclusion at that meeting that keyref can only go to topics (from map) or topics + subelements (from topic), we should definitely call that out here.

For elements that only refer to topics or non-DITA resources, the value of the @keyref attribute is a key name. For elements that can refer to elements within maps or topics, the value of the @keyref attribute is a key name, a slash ("/"), and the ID of the target element, where the key name must be bound to either the map or topic that contains the target element.