What is conkeyref (conditional key reference) in DITA?

Conkeyref is a mechanism in DITA that allows for more precise and flexible content reuse compared to standard conref (content referencing). It enables the selective referencing of specific elements or attributes within a topic, making it a powerful tool for content modularity and reuse.

Conkeyref involves:

  1. Selective Referencing: Conkeyref allows referencing not only entire topics but also specific elements or attributes within topics. This granular control over what is reused is particularly useful to repurpose content within a different context.
  2. Keys and Key References: In DITA, a key is a unique identifier assigned to an element or attribute to reuse. In the source topic, a key is assigned to the element or attribute to be referenced. In the target topic, the key reference (conkeyref) is used to specify which element or attribute should be reused.
  3. Attributes and Elements: Conkeyref can be applied to both elements and attributes, providing flexibility in what to reuse. Content can be referenced from an attribute within an element or even reuse entire elements from the source topic.
  4. Content Variations: Conkeyref also allows variations in content between source and target topics. This means a core piece of content in the source can then have content added or modified in the target topic, while still keeping the connection to the source.


A product description in the source topic with a unique identifier (key) is assigned to a specific attribute and an element:

Source Topic (source.dita):

          <name id="p1">Product A</name>
          <description>Product A is a versatile solution for your needs.</description>

In the target topic, the product name will be reused but with a different description:

Target Topic (target.dita):

          <name conkeyref="p1"/>
          <description>Product A is the latest addition to our product line.</description>

In this example, conkeyref=”p1″ points to the “name” element with the key “p1” in the source topic, allowing the reuse of the product name while providing a modified description. Conkeyref enables this level of content control and adaptability in DITA content reuse.