DITA map elements

Darwin Information Typing Architecture (DITA) Version 1.3 Part 2: Technical Content Edition

OASIS DITA Technical Committee

A DITA map describes the relationships among a set of DITA topics. The DITA map and map-group domain elements organize topics into hierarchies, groups, and relationships; they also define keys.

A DITA map is composed of the following elements:

The map element is the root element of the DITA map.

The topicref elements are the basic elements of a map. A topicref element can reference a DITA topic, a DITA map, or a non-DITA resource. A topicref element also can have a title, short description, and the same kind of prolog-level metadata that is available in topics.

The topicref elements can be nested to create a hierarchy, which can be used to define a table of contents (TOC) for print output, online navigation, and parent/child links. Hierarchies can be annotated using the collection-type attribute to define a particular type of relationship, such as a set of choices, a sequence, or a family. These collection types can affect link generation, and they might be interpreted differently for different outputs.


Relationship tables are defined with the reltable element. Relationship tables can be used to define relationships among DITA topics or among DITA topics and non-DITA resources. In a relationship table, the columns define common attributes, metadata, or information types (for example, task or troubleshooting) for the resources that are referenced in that column. The rows define relationships between the resources in different cells of the same row.

The relrow, relcell, relheader, and relcolspec elements are used to define the components of the relationship table. Relationships defined in the relationship table also can be further refined by using the collection-type attribute.

The topicgroup element defines a group or collection outside of a hierarchy or relationship table. It is a convenience element that is equivalent to a topicref element without an href attribute or navigation title. Groups can be combined with hierarchies and relationship tables, for example, by including a topicgroup element within a set of siblings in a hierarchy or within a table cell. The topicref elements so grouped can then share inherited attributes and linking relationships with no effect on the navigation or table of contents.
Most map-level elements, including the map itself, can contain metadata inside the topicmeta element. Metadata typically is applied to an element and its descendants.
The ux-window element enables authors to define windowing information for the display of output topics that are appropriate to the delivery platform. Window management is important in user assistance and help system outputs, as well as for other hypertext and electronic delivery modes.
The topichead element provides a navigation title; it is a convenience element that is equivalent to a topicref element with a navigation title but no associated resource.
The anchor element provides an integration point that another map can reference in order to insert its navigation into the referenced map's navigation tree. For those familiar with Eclipse help systems, this serves the same purpose as the anchor element in that system. It might not be supported for all output formats.
The navref element represents a pointer to another map which is preserved as a transcluding link in the result deliverable rather than resolved when the deliverable is produced. Output formats that support such linking can integrate the referenced resource when displaying the referencing map to an end user.
Enables authors to define keys. This element is a convenience element; it is a specialization of topicref that sets the default value of the processing-role attribute to "resource-only". Setting the processing-role attribute to resource-only ensures that the resource referenced by the key definition is not directly included in the navigation that is defined by the map.
Enables authors to reference an entire DITA map, including hierarchy and relationship tables. This element is a convenience element; it is a specialization of topicref that sets the default value of the format attribute to "ditamap". The mapref element represents a reference from a parent map to a subordinate map.
Enables authors to define a branch of navigation in a DITA map so that it can be referenced from another DITA map.
Enables authors to reference a navigation branch that is defined in another DITA map.
Enables authors to define a map fragment that is pushed to the location defined by an anchor.