Skip to main content
January 26, 2015

DITA 1.3 overview

Robert Anderson, one of the DITA architects, compared the transition from DITA 1.1 to DITA 1.2 to the difference between having a couple of drinks with friends and a huge party. The DITA 1.2 specification introduced broad changes in the form of new base elements, new architectural structures, and new specializations.

DITA 1.3 isn’t the rowdy gathering that DITA 1.2 was—it’s more a group of friends going out to the new pub downtown while being sure to get some designated drivers. This article describes the most important additions to DITA 1.3.

Scoped keys

In DITA 1.2, keys were always global. That is, a key could only use one value in a ditamap. If you needed a key to use two different values in different parts of a single ditamap file, you were out of luck.

DITA 1.3 addresses this problem with the @keyscope attribute. The @keyscope attribute lets you constrain the value of a key to a specific part of the ditamap. In effect, you create a local key instead of a global key. This is useful for omnibus publications or for publications that are authored by multiple teams. For example, consider a widget repair manual that describes two different products. It needs to reference the prodinfo key, but with two different values. The @keyscope attribute supports this requirement.


<title>Widget Repair Manual</title>
<topichead navtitle=”Widget A” keyscope=”Widget_A”>
<keydef keys=”prodinfo” href=”prodinfo_a.dita”/>
<topicref href=”maintenance_a.dita”/>
<topichead navtitle=”Widget B” keyscope=”Widget_B”>
<keydef keys=”prodinfo” href=”prodinfo_b.dita”/>
<topicref href=”maintenance_b.dita”/>


Before DITA 1.3, this scenario required two different keys or separate publications for each widget. To reference a key within a specific scope, add a scope before the key name. For example, to explicitly reference Widget B’s product information, use Widget_B.prodinfo as the key value. If no scope is declared, the scope of the current topic is used instead.

Cross-deliverable linking

DITA 1.3 also provides support for cross-deliverable linking through scoped keys. First, you create a mapref, set the @scope attribute to peer, and then define a keyscope.


<title>Widget User Guide</title>
<mapref href=”../Repair_Manual/Repair_Manual.ditamap” scope=”peer” keyscope=”Repair_Manual”/>


Then you can use keys contained in the referenced map within the publication. In this example, topics within the Widget User Guide can use keys that are defined in Repair_Manual.ditamap. For example, to reference a task detailing the repair of a feature, an author could do the following:

<p>If replacing the module did not work, see <xref keyref=”Repair_Manual.wiring_harness”/> in <conkeyref=”Repair_Manual.title”/> for detailed instructions on how to repair the wiring harness.</p>

Branch filtering

In DITA 1.2, ditavals are global and applied when running a transform. In DITA 1.3, the <ditavalref> element allows you to specify ditavals at the map or topicref level and then cascade the filtering effects through the map. Consider a software documentation guide.


<title>App User Manual</title>
<topicref href=”prodinfo.dita>

          <ditavalref href=”user.ditaval”/>

<topicref href=”functions.dita”>

<ditavalref href=”mac.ditaval”/>
<ditavalref href=”windows.ditaval”/>
<ditavalref href=”linux.ditaval”/>



When output is generated from this map, prodinfo.dita is published using the settings in user.ditaval. In addition, functions.dita is published three times, once for each of the three ditaval files specified.


The new troubleshooting topic type is a specialization of the task topic type intended for troubleshooting steps, and consists of <condition>, <cause>, and <remedy> elements. You can use multiple cause/remedy pairs to provide a series of corrective actions for conditions that can have multiple causes.

The optional <tasktroubleshooting> and <steptroubleshooting> elements and trouble admonition type are used to provide quick, embedded troubleshooting within a topic. The DITA 1.3 specification recommends that these elements contain a condition, cause, and remedy.

The big picture

There are a lot of new toys to work with in DITA 1.3, and we haven’t even looked at some of the smaller additions, like new attributes for tables and organizational elements within topics. There are a lot of necessities to consider, but will your vendors support them, and how soon?

How could some of these new features be used to your advantage? Have you already implemented similar functionality yourself?