Metadata in maps and topics

Darwin Information Typing Architecture (DITA) Version 1.3 Part 3: All-Inclusive Edition

Darwin Information Typing Architecture (DITA) Version 1.3 Part 3: All-Inclusive Edition
OASIS DITA Technical Committee

Topic metadata can be specified in a DITA map as well as in the topics that the map references. By default, metadata in the map supplements or overrides metadata that is specified at the topic level, unless the lockmeta attribute of the topicmeta element is set to "no".

Where metadata about topics can be specified

Information about topics can be specified as metadata on the map, as attributes on the topicref element, or as metadata attributes or elements in the topic itself:
DITA map: Metadata elements

At the map level, properties can be set by using metadata elements. They can be set for an individual topic, for a set of topics, or globally for the entire document. The metadata elements are authored within a topicmeta element, which associates metadata with the parent element and its children. Because the topics in a branch of the hierarchy typically have some common subjects or properties, this is a convenient mechanism to define properties for a set of topics. For example, the topicmeta element in a relcolspec can associate metadata with all the topics that are referenced in the reltable column.

A map can override or supplement everything about a topic except its primary title and body content. All the metadata elements that are available in a topic also are available in a map. In addition, a map can provide alternate titles and a short description. The alternate titles can override their equivalent titles in the topic. The short description in the map MAY override the short description in the topic if the topicref element specifies a copy-to attribute.

DITA map: Attributes of the topicref element
At the map level, properties can be set as attributes of the topicref element.
DITA topic
Within a topic, authors can either set metadata attributes on the root element or add metadata elements in the prolog element.

How metadata set at both the map and topic level intersects

In a topic, the metadata elements apply to the entire topic. In a map, they supplement or override any metadata that is provided in the referenced topics. When the same metadata element or attribute is specified in both a map and a topic, by default the value in the map takes precedence; the assumption here is that the author of the map has more knowledge of the reusing context than the author of the topic. The lockmeta attribute on the topicmeta element controls whether map-specified values override values in the referenced topic.

The navtitle element is an exception to the rule of how metadata specified by the topicmeta element cascades. The content of the navtitle element is used as a navigation title only if the locktitle attribute of the parent topicref element is set to "yes".