Cascading of attributes and metadata in a DITA map

Darwin Information Typing Architecture (DITA) Version 1.2

Certain map-level attributes and metadata elements cascade throughout a map, which facilitates attribute and metadata management. When attributes or metadata elements cascade, they apply to the elements that are children of the element where the attributes or metadata were specified. Cascading applies to a containment hierarchy, as opposed to a element-type hierarchy.
The following attributes and metadata elements cascade throughout the entire map:
  • Attributes set on the <map> element
  • Metadata elements that are contained in the <topicmeta> element that is a child of the <map> element
Attribute values and metadata elements in relationship tables can be applied to entire columns or rows as well as individual cells, a practice that is particularly useful for attribute and metadata management.

Attributes and metadata that cascade

The following attributes and metadata elements cascade:
Attributes
  • @audience, @platform, @product, @otherprops, @rev
  • @props and any attribute specialized from @props
  • @linking, @toc, @print, @search
  • @format, @scope, @type
  • @xml:lang, @dir, @translate
  • @processing-role
Metadata elements
  • author, source, publisher, copyright, critdates, permissions
  • audience, category, prodinfo, othermeta
Cascading is additive for attributes and metadata elements that accept multiple values. For attributes that take a single value, the closest value defined on a containing element takes effect. In a relationship table, row-level metadata is considered more specific than column-level metadata, as shown in the following containment hierarchy:
  • <map> (most general)
    • <topicref> container (more specific)
      • <topicref> (most specific)
    • <reltable> (more specific)
      • <relcolspec> (more specific)
        • <relrow> (more specific)
          • <topicref> (most specific)

Rules for cascading in the map

When determining the value of an attribute, processors must evaluate each attribute on each individual element in a specific order; this order is specified in the following list. Applications should continue through the list until a value is established or until the end of the list is reached (at which point no value is established for the attribute). In essence, the list provides instructions on how processors can construct a map where all attribute values are set and all cascading is complete.

For example, in the case of <topicref toc="yes>, applications must stop at 2 in the list; a value is specified for @toc in the document instance, so @toc values from containing elements will not cascade to that specific <topicref> element. The @toc="yes" setting on that <topicref> element may cascade to contained elements, provided those elements reach 5 below when evaluating the @toc attribute.

For attributes within a map, the following processing order must occur:
  1. The @conref and @keyref attributes are evaluated.
  2. The explicit values specified in the document instance are evaluated. For example, a <topicref> element with the @toc attribute set to "no" will use that value.
  3. The default or fixed attribute values that are expressed within DTDs or XSDs are evaluated. For example, in the DTDs and XSDs, the @toc attribute on the <reltable> element has a default value of "no".
  4. The default values that are supplied by a controlled values file are evaluated.
  5. The attributes cascade.
  6. The processing-supplied default values are applied.
  7. After the attributes are resolved within the map, they cascade to referenced maps.
    Note: The processing-supplied default values do not cascade to other maps. For example, most processors will supply a default value of @toc="yes" when no @toc attribute is specified. However, a processor-supplied default of toc="yes" must not override a value of toc="no" that is set on a referenced map. If the toc="yes" value is explicitly specified, is given as a default through a DTD, XSD, or controlled values file, or cascades from a containing element in the map, it will override a toc="no" setting on the referenced map. See Map-to-map cascading behaviors for more details.
  8. Repeat steps 1 to 4 for each referenced map.
  9. The attributes cascade within each referenced map.
  10. The processing-supplied default values are applied within each referenced map.
  11. Repeat the process for maps referenced within the referenced maps.

Example of metadata elements cascading in a DITA map

The following code sample illustrates how an information architect can apply certain metadata to all the DITA topics in a map:
<map title="DITA maps" xml:lang="en-us">
	<topicmeta>
		<author>Kristen James Eberlein</author>
		<copyright>
			<copyryear year="2009"/>
			<copyrholder>OASIS</copyrholder>
		</copyright>
	</topicmeta>
	<topicref href="dita_maps.dita" navtitle="DITA maps">
		<topicref href="definition_ditamaps.dita" navtitle="Definition of DITA maps"></topicref>
		<topicref href="purpose_ditamaps.dita" navtitle="Purpose of DITA maps"></topicref>
		...
</map>

The author and copyright information cascades to each of the DITA topics referenced in the DITA map. When the DITA map is processed to XHTML, for example, each XHTML files contains the metadata information.