Defining Keys in DITA Maps

DITA uses keys to insert content that may have different values in various circumstances. Keys provide the means for indirect referencing in DITA. This can make it easier to manage and to reuse content. In DITA, keys are defined in maps and can then be reused and referenced throughout the whole structure of the map. It is considered best practice to create a separate submap that contains all of the key definitions and reference that submap in the main (root) map. This makes it easier to manage since they're all in one location.

There are two types of key definitions that can be created in a map.

Key with a value inside a keyword.
Key with a target (for example, to target a resource such as an image or external link).

The following example is a DITA map (a key definition submap) that contains some key definitions with various values for the product key and some targets to external URLs:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
<map id="keydefs">
  <!-- product name -->
  <title>Key Definitions</title>
  <keydef keys="product" product="basic">
    <topicmeta>
      <keywords>
        <keyword>Basic Widget</keyword>
      </keywords>
    </topicmeta>
  </keydef>
  <keydef keys="product" product="pro">
    <topicmeta>
      <keywords>
        <keyword>Professional Widget</keyword>
      </keywords>
    </topicmeta>
  </keydef>
  <keydef keys="url_eula" href="https://www.example.com/eula.html" format="html"
     scope="external"/>
  <keydef keys="url_eula2" href="https://www.example.com/eula2.html" format="html"
     scope="external"/>
</map>

Note: The profiling of the names is now contained in the map, where it only has to occur once to reuse throughout the whole map structure.

Key Definition with a Keyword Value

To define a key with a value inside a keyword, follow these steps:

[Optional but Recommended] Create a submap that will contain all of your key definitions and reference the submap in your main (root) map (if you don't already have one created).
Open that map in the DITA Maps Manager.
Right-click the map or an item in the map where you want to add the reference and select Key Definition with Keyword from the Append Child, Insert Before, or Insert After submenu (depending on where you want to insert the key definition). This opens an Insert Key Definition dialog box.
Enter the name of the key in the Key field.
Enter the key's value in the Keyword field.
Click Insert and close.
Tip: If you need to profile the key or add other attributes, you can right-click the key definition in the DITA Maps Manager, select Edit properties, and configure them in the Profiling tab or Attributes tab, respectively.

Key Definition with a Target

To insert a targeted key definition (for example, to target a resource such as an image or external link), follow these steps:

[Optional but Recommended] Create a submap that will contain all of your key definitions and reference the submap in your main (root) map (if you don't already have one created).
Open that map in the DITA Maps Manager.
Right-click the map or an item in the map where you want to add the reference and select Key Definition from the Append Child, Insert Before, or Insert After submenu (depending on where you want to insert the key definition in the DITA map). This opens an Insert Key Definition dialog box.
Go to the Keys tab and enter the name of the key in the Define keys field.
Go to the Target tab and select a target resource (such as an image or external link).
Tip: You can profile the key by using the Profiling tab and other attributes can also be defined in the Attributes tab.
Once you are done configuring the targeted key definition, click Insert and close.