In DITA, both <xref> and key references play crucial roles in linking and referencing content across topics. <xref> provides a way to create cross-references, while key references enable reusability and consistency in content.

<xref> is used to create cross-references within DITA content. It allows linking to another DITA topic or specific content within the same or different topics. It typically uses the href attribute to specify the target location, which can be a DITA topic ID or a key reference.

Key references in DITA involve defining and referencing content using keys and key references. Keys are user-defined identifiers, while key references link to content via these keys. Key references are useful for reusing content, ensuring consistency, and simplifying updates across topics. Keys can be defined by the content creator, which then allows that content to be referenced using those keys.

The primary relationship between <xref> and key references is that an <xref> can be used to link to content that has been defined or marked with key references. This provides a way to access and reuse specific content blocks across topics.

Example:

A documentation set includes two DITA topics, one on “Product Specifications” and another on “Startup Procedure” The “Startup Procedure” topic needs a cross-reference to a specific technical term defined in the “Product Specifications” topic using key references:

Product Specifications Topic (product_spec.dita):

<topic id="product_spec">
  <title>Product Specifications</title>
  <p>This product has a key feature: <term id="key_feature">Key Feature X</term>.</p>
</topic>

Startup Procedure Topic (user_manual.dita):

<topic id="user_manual">
  <title>Startup Procedure</title>
  <p>Refer to the <xref href="product_spec.dita#key_feature">product specifications</xref> for more details on Key Feature X.</p>
</topic>

In this example:

• In the “Product Specifications” topic, the term “Key Feature X” was defined and given the <term> element with an id attribute. This creates a key reference for that term.
• In the “Startup Procedure” topic, an <xref> element is used to create a cross-reference to the “Product Specifications” topic, specifically to the term “key_feature” defined within it. This links readers to more information about “Key Feature X” without duplicating content.