Topic properties in topics and maps

The properties of a topic (including metadata attributes and metadata elements) can be specified in the topic itself or in references to the topic within maps.

Within a topic, properties can be expressed using metadata attributes on the topic element or using publication, management, or metadata elements in the topic prolog.

DITA offers users three levels at which to apply topic properties. Topic attributes and metadata elements can be defined within the topic itself. Properties can also be set as attributes or subelements of a topicref that points to the topic. In addition, properties can be set on container or ancestor elements of the topicref within the map. Because the topics in a branch of the navigation hierarchy typically have some common subjects or properties, this is a convenient mechanism to set properties for a set of topics.

If a property is set in both the map and topic, the map properties are additive if the property (such as the audience type) takes a list of values. If, instead, the property (such as the importance) takes a single value, the map property overrides the topic property.

Example of audience metadata in prolog and body

Prolog metadata elements can provide more information about values used in metadata attributes on content. However, prolog metadata and attribute metadata can also 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 is administrators who are customizing and are new at it.

Metadata inheritance between maps and topics
The topicmeta element in maps contains numerous elements for the declaration of metadata. In general, specifying metadata in a topicmeta element is equivalent to specifying it in the topic, while allowing that topic to be reused in other maps where the metadata does not apply. Many items in the metadata also cascade to nested topic references within the map.

Parent topic: Metadata elements and common attributes

Previous topic: Common attributes

Shared metadata elements, and the lockmeta attribute

You can associate topic metadata with a topic or branch of topics in a map. By default metadata in the map supplements or overrides metadata in the topic. If the lockmeta attribute is set to "no", then the metadata in the map will not take precedence over the metadata in the topic, and conflicts will be resolved in favor of the topic.

In a map, metadata elements are authored within a <topicmeta> element, which associates metadata with the <topicref> or other element that contains it, plus the other children of that element. For example, <topicmeta> in a <relcolspec> can associate metadata with all the topics referenced in a <reltable> column.

The metadata elements in a map are the same as those in a topic, although they may be in a different order. The map metadata also includes a short description and alternate titles, which can override their equivalents in the content. In sum, the map can override or supplement everything about a topic except its content (in the topic's body element) and primary title.

Metadata inheritance between maps and topics
The topicmeta element in maps contains numerous elements for the declaration of metadata. In general, specifying metadata in a topicmeta element is equivalent to specifying it in the topic, while allowing that topic to be reused in other maps where the metadata does not apply. Many items in the metadata also cascade to nested topic references within the map.

Parent topic: Metadata elements and common attributes

Previous topic: Common attributes