Metadata in maps and topics

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, plus the other children of that element. Because the topics in a branch of the hierarchy typically have some common subjects or properties, this is a convenient mechanism to set 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 may provide alternate titles and a short description. The alternate titles can override their equivalents in the topic. The short description in the map may override the short description in the topic if both following conditions are true:

• The <topicref> element specifies a @copy-to attribute.
• The processor implements this behavior. Processors may or may not implement this behavior.

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 is handled

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, on the assumption that the author of the map has more knowledge of the reusing context than the author of the topic had. 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 is propagated. 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".

Associating attribute-based metadata with element-based metadata

At the topic level, the content of the prolog metadata elements can provide more information about the values that are used for attributes on the elements in the body of the DITA topic. However, prolog metadata and attribute metadata also can be used and expressed independently. The coordination shown here is possible but is not required.

<prolog>
  <metadata>
    <audience name="AdminNovice"
              type="administrator"
              job="customizing"
              experiencelevel="novice">

  </metadata>
</prolog>
....
<p audience="AdminNovice ProgrammerExp">This paragraph applies to both 
novice administrators and expert programmers</p>

In the preceding example, the attribute value AdminNovice is associated with the audience element with the same name, which gives authors and processes more information about the audience in question: in this case, that the "AdminNovice" audience consists of administrators who are customizing and who are new at it.