ID attribute

The DITA identity attribute provides a mechanism for identifying content for linking.

The id attribute assigns an identifier to DITA elements so the elements can be referenced. The id attribute is available for most elements. The id attribute is required on some elements. For a specific element to be referenced, it must have an id attribute with a valid value, although entire maps and the first topic, only topic, or all direct-child topics (depending on processing context) in a topic-containing document may be referenced without using an ID. The requirements for the id attribute differ depending on whether it is used on a topic element, a map element, or an element within a topic or map.

The id attributes for topic and map elements are true XML IDs and therefore must be unique with respect to other XML IDs within the scope of the XML document that contains the topic or map element. The id attribute for most other elements within topics and maps are not declared to be XML IDs. This means that XML parsers do not require that the values of those attributes be unique. All id attribute values must be XML name tokens.

Within documents containing multiple topics, the IDs for all non-topic elements that have the same nearest ancestor topic element should be unique with respect to each other. The IDs for non-topic elements may be the same as non-topic elements with different nearest ancestor topic elements.


Thus, within a single XML document containing multiple peer or nested topics, the IDs of the non-topic elements only need to be unique within each topic without regard to the IDs of elements within any ancestor or descendant topics.

The IDs of all elements within a map should be unique within that map document. When two elements within a map have the same ID value, the first element with a given ID value, in document order, must be used as the target of any reference to that ID.

ID requirements summary table

Element Attribute type Unique within Required Value type
map ID document No XML non-colonized name token
topic ID document Yes XML non-colonized name token
sub-map NMTOKEN document Usually no, with some exceptions Any legal XML name token
sub-topic NMTOKEN individual topic Usually no, with some exceptions Any legal XML name token

Was this helpful?