IDs and references

The DITA identity attribute provides mechanisms for identifying content for retrieval or linking. The syntax for referencing IDs is consistent regardless of the referencing mechanism.

The id attribute assigns a unique identifier to an element so the element can be referenced. The scope of uniqueness for the id attribute depends on the role of the element within the DITA architecture:

Topic IDs

Because topics are the basic units of information within DITA, the id attribute for the topic must be unique within the document instance.

A topic architecture assembles topics into a deliverable by reference. To ensure that topics can be referenced, the id attribute is required on the topic element.

The complete identifier for a topic consists of the combination of the URI for the document instance, a separating hash character, and the topic id (as in http://some.org/some/directory/topicfile.xml#topicid). URIs are described in RFC 2396. As is typical with URIs, a relative URI can be used as the identifier for the document instance so long as it is resolvable in the referencing context. For instance, within a file system directory, the filename of the document instance suffices (as in some/directory/topicfile.xml#topicid). Within the same document, the topic id alone suffices (as in #topicid). Where the topic element is the root element of the document instance, contexts outside the document instance may omit the topic id when referring to the topic element (as in topicfile.xml). If the target contains multiple peer topics organized by a <dita> element (as in the ditabase document type), then the reference is resolved to the first topic in the target, except in the case of topicrefs being resolved as inclusion directives (for example during PDF output), in which case the entire target file is included, regardless of whether a specific topic is targeted.

The topic id can be referenced by other elements, including topicrefs, links, xrefs, or conrefs to the topic, as well as being used as part of references to the topic content.

The id attribute for DITA topics is of type ID in XML, and so must be unique within the document instance.

Element IDs within a topic

Because topic content is always contained within a topic, the id attribute for a topic content element must be unique only within the one topic that immediately contains it. This approach ensures maintainable references to content because the identifier remains valid so long as the document instance, topic, and content exist. The position of the content within the topic and the position of the topic within the document instance can change without invalidating the content identifier. In addition, this approach avoids the need to rewrite topic content ids to avoid naming collisions when aggregating topics.

The id is optional and need be added only to make the content referenceable.

The complete identifier for topic content consists of the combination of the complete identifier for the topic, a separating solidus (/), and the topic content id (as in http://some.org/some/directory/topicfile.xml#topicid/contentid). As noted before, the topic identifier portion can use a relative URI for the document instance in contexts where the relative URI can be resolved (as in some/directory/topicfile.xml#topicid/contentid).

The containing topic id must always be included when referencing an element id. Otherwise, a reference to another topic couldn't be distinguished from a reference to an element within the same topic. For references within the same document instance, the identifier for the document instance can be omitted altogether (as in #topicid/contentid).

The id attribute for elements within DITA topics is not of type ID and is not required to be unique within a document, although it should be unique within the topic.

Map IDs and element IDs within a map

For a map, the id of an element should be unique within the document instance. This approach ensures that these elements can be referenced outside the map without qualification by the map id.

For the anchor element, which exists only to identify a position within a map as a target for references, the id attribute is required. For the other elements, the id attribute is optional.

The complete identifier for a map element consists of the combination of the absolute URI for the map document instance and the element id (as in http://some.org/some/directory/mapfile.xml#topicrefid).

The id attributes for maps and anchors are of type ID and are required to be unique within the document instance. The id attributes for other elements in map are not of type ID and are not required to be unique.