DITA linking

Darwin Information Typing Architecture (DITA) Version 1.3 Part 1: Base Edition

OASIS DITA Technical Committee

DITA supports many different linking elements, but they all use the same set of attributes to describe relationships between content.

URI-based addressing

URI-based links are described by the following attributes.

The href attribute specifies the URI of the resource that is being addressed.
The format attribute identifies the format of the resource being addressed. For example, references to DITA topics are identified with format="dita", whereas references to DITA maps use format="ditamap". References to other types of content should use other values for this attribute. By default, references to non-XML content use the extension of the URI in the href attribute as the effective format.
The scope attribute describes the closeness of the relationship between the current document and the target resource. Resources in the same information unit are considered "local"; resources in the same system as the referencing content but not part of the same information unit are considered "peer"; and resources outside the system, such as Web pages, are considered "external".
The type attribute is used on cross-references to describe the target of the reference. Most commonly, the type attribute names the element type being referenced when format="dita".

These four attributes act as a unit, describing whatever link is established by the element that carries them.

The format and scope attributes are assigned default values based on the URI that is specified in the href attribute. Thus they rarely need to be explicitly specified in most cases. However, they can be useful in many non-traditional linking scenarios or environments.

Indirect key-based addressing

DITA also supports indirect links and cross-references in which a DITA map assigns unique names, or keys, to the resources being referenced by the publication. This is done using topicref elements that specify the keys attribute. Using the keyref attribute, individual links, cross-references, and images then reference resources by their keys instead of their URIs . Links defined using keyref thus allow context-specific linking behavior. That is, the links in a topic or map might resolve to one set of resources in one context, and a completely different set of resources in another, without the need for any modifications to the link markup.

When links are defined using keyref, values for the four linking attributes described above are typically all specified (or given default values) on the key defining element.