Cascading metadata

Metadata cascading is the process by which metadata elements and attributes specified for a map or for a topic reference cascade to nested references. This allows metadata properties to be set once and apply to an entire map or branch of a map.

Cascading of metadata attributes in a DITA map

Certain attributes cascade throughout a map, which facilitates attribute and metadata management. When attributes cascade, they apply to the elements that are children of the element where the attributes were specified. Cascading applies to a containment hierarchy, as opposed to a specialization hierarchy.

The following attributes cascade when set on the <map> element or when set within a map:

  • @rev
  • @props and any attribute specialized from @props, including those integrated by default in the OASIS-provided document-type shells: @audience, @deliveryTarget, @platform, @product, @otherprops
  • @linking, @toc, @search
  • @format, @scope, @type
  • @xml:lang, @dir, @translate
  • @processing-role
  • @cascade
  • @subjectrefs

Cascading is additive for attributes that accept multiple values, except when cascade="nomerge" is specified. For attributes that take a single value, the value that is defined on the closest containing element takes effect.

In a relationship table, metadata can be applied to entire rows or columns, as well as individual cells. The metadata cascade operates differently due to the nature of this tabular structure The cascade is not driven by a strict containment hierarchy because <relcolspec> elements do not contain child elements.

The following list illustrates how metadata cascades in a relationship table:

  • <reltable>
    • <relcolspec>
      • <relrow>
        • <relcell>
          • <topicref>

Processing cascading attributes in a map

Certain rules apply to processors when they process cascading attributes in a 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 MUST 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 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 are evaluated. For example, 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, any values that do not come from processing-supplied defaults will cascade to referenced 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" does 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, RNG, 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.

For example, in the case of <topicref toc="yes">, applications must stop at item 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 will cascade to contained elements, provided those elements reach item 5 when evaluating the @toc attribute.

Merging of cascading attributes

The @cascade attribute can be used to modify the additive nature of attribute cascading, although it does not turn off cascading altogether. The attribute has two predefined values: merge and nomerge.

merge
Indicates that the metadata attributes cascade, and that the values of the metadata attributes are additive. This is the processing default for the @cascade attribute.
nomerge
Indicates that the metadata attributes cascade, but that they are not additive for <topicref> elements that specify a different value for a specific metadata attribute. If the cascading value for an attribute is already merged based on multiple ancestor elements, that merged value continues to cascade until a new value is encountered. That is, setting cascade="nomerge" does not undo merging that took place on ancestor elements.

If no value is set for the @merge attribute and no value cascades from a containing element, processors SHOULD assume a default of merge.

Implementers MAY define their own custom, implementation-specific tokens for the @merge attribute. To avoid name conflicts between implementations or with future additions to the standard, implementation-specific tokens SHOULD consist of a prefix that gives the name or an abbreviation for the implementation followed by a colon followed by the token or method name. For example, a processor might define the token "appToken:audience" in order to specify cascading and merging behaviors for only the @audience attribute.

The predefined values for the @cascade attribute MUST precede any implementation-specific tokens, for example, cascade="merge appToken:audience".

Reconciling topic and map metadata elements

The <topicmeta> element in maps can contain numerous metadata elements. These metadata elements can have an effect on the parent <topicref> element, any child <topicref> elements, and – if a direct child of the <map> element – on the .

For each element that can be contained in the <topicmeta> element, the following table addresses the following questions:
How does it apply to the topic?
This column describes how the metadata specified within the <topicmeta> element interacts with the metadata specified in the referenced topic. In most cases, the properties are additive. For example, when a topic reference in a map contains <category>installation</category>, <category>installation</category> is added during processing to any metadata that is specified in the topic prolog.
Does it cascade to other topics in the map?
This column indicates whether the specified metadata element cascades to nested <topicref> elements. For example, when a topic reference in a map contains <author>Jane Doe</author>, <author>Jane Doe</author> is added during processing to the metadata for all child topic references. Some elements do not cascade.
What is the purpose when specified on the <map> element?
The map element permits metadata to be specified for the map. This column describes the effect that an element has when specified at this level.
When set on the <map> element, does it apply to all topics referenced in the map?
When specified on the <map> element element, some metadata elements then apply to all the topics that are referenced in the map.
Table 1. <topicmeta> elements and their properties
Element How does it apply to the topic? Does it cascade to child <topicref> elements? What is the purpose when set on the <map> element? When set on the <map> element, does it apply to all topics referenced in the map?
<audience> Add to the topic Yes Specify an audience for the map Yes
<author> Add to the topic Yes Specify an author for the map Yes
<category> Add to the topic Yes Specify a category for the map Yes
<copyright> Add to the topic Yes Specify a copyright for the map Yes
<critdates> Add to the topic Yes Specify critical dates for the map Yes
<data> Add to the topic No, unless specialized for a purpose that cascades No stated purpose No
<foreign> Add to the topic No, unless specialized for a purpose that cascades No stated purpose No
<keytext> Not added to the topic No No stated purpose No
<keywords> Add to the topic No No stated purpose No
<metadata> Add to the topic Yes Specify metadata for the map Yes
<othermeta> Add to the topic No Define metadata for the map Yes
<permissions> Add to the topic Yes Specify permissions for the map Yes
<prodinfo> Add to the topic Yes Specify product info for the map Yes
<publisher> Add to the topic Yes Specify a publisher for the map No
<resourceid> Add to the topic No Specify a resource ID for the map itself No
<shortdesc> Applies only to links created based on this occurrence in the map No Provide a description of the map No
<source> Add to the topic No Specify a source for the map No
<titlealt> Add to the topic before its <titlealt> elements No Specify an alternative title for the map No
<ux-window> Not added to the topic No Definitions are global, so setting at map level is equivalent to setting anywhere else. No

Map-to-map cascading behaviors

When a DITA map or map branch is referenced by another DITA map, by default certain rules apply. These rules pertain to the cascading behaviors of attributes, metadata elements, and the roles that are assigned to content , for example, the role of "Chapter" that is assigned by a <chapter> element. Attributes and elements that cascade within a map generally follow the same rules when cascading from one map to another map, but there are some exceptions and additional rules that apply.

Cascading of attributes from map to map

Certain attributes cascade from map to map.

The following attributes cascade from map to map:

  • @rev
  • @props and any attribute specialized from @props, including those integrated by default in the OASIS-provided document-type shells: @audience, @deliveryTarget, @platform, @product, @otherprops
  • @linking, @toc, @search
  • @type
  • @translate
  • @processing-role
  • @cascade
  • @subjectrefs

As with values that cascade within a map, the cascading is additive if the attribute permits multiple values, such as @audience. For attributes that take a single value, the value that is defined on the closest containing element takes effect.

The following attributes do not cascade from map to map
@format
The @format attribute is set to ditamap when a map or map branch is referenced, so it cannot cascade through to the referenced map.
@scope
The value of the @scope attribute describes the map itself, rather than the content. For example, when the @scope attribute is set to external, it indicates that the referenced map itself is external and unavailable, so the value cannot cascade into that referenced map.
@xml:lang and @dir
Cascading behavior for @xml:lang is defined in The xml:lang attribute. The @dir attribute follows the same rules as @xml:lang.

While the @class attribute is unique and does not cascade, the value of the attribute is used to determine the processing roles that cascade from map to map. See Cascading of roles from map to map for more information.

Cascading of metadata elements from map to map

Elements that are contained within <topicmeta> elements follow the same rules for cascading from map to map as the rules that apply within a single DITA map.

For a complete list of which elements cascade within a map, see the column "Does it cascade to child <topicref> elements?" in the topic Reconciling topic and map metadata elements.

Note (non-normative):
It is possible that a specialization might define metadata that is intended to replace rather than add to metadata in the referenced map, but DITA, by default, does not have a mechanism to specify this behavior.

Examples of metadata cascading

This section is non-normative.

These examples illustrate the processing expectations for cascading metadata. The processing examples use either before and after sample markup or expanded syntax that shows the equivalent markup withough cascading.

Example: How map-level metadata elements cascade to the referenced topics

This section is non-normative.

In this scenario, elements located in the<topicmeta> element for a map cascade to the referenced topics.

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

The author and copyright information cascades to each of the DITA topics that are referenced in the DITA map. When the DITA map is processed to HTML5, for example, the author and copyright metadata apply to each generated HTML5 file.

Example: How metadata elements cascade from one map to another

This section is non-normative.

In this scenario, a metadata element that is located in a map reference cascades to the topics that are referenced in a nested map.

Assume the following references in test.ditamap:
<map>
  <topicref href="a.ditamap" format="ditamap" toc="no"/>
  <mapref href="b.ditamap" audience="developer"/>
  <mapref href="c.ditamap#branch2" platform="myPlatform"/>
  <mapref href="d.ditamap" subjectrefs="puzzles"/>
</map>
  • The map a.ditamap is treated as if toc="no" is specified on the root <map> element. This means that the topics that are referenced by a.ditamap do not appear in the navigation generated by test.ditamap, except for branches within the map that explicitly set toc="yes".
  • The map b.ditamap is treated as if audience="developer" is set on the root <map> element. If the @audience attribute is already set on the root <map> element within b.ditamap, the value developer is added to any existing values.
  • The element with id="branch2" within the map c.ditamap is treated as if platform="myPlatform" is specified on that element. If the @platform attribute is already specified on the element with id="branch", the valuemyPlatform is added to existing values.
  • The map d.ditamap is treated as if subjectrefs="puzzles" is set on the root <map> element. If the @subjectrefs attribute is already set on the root <map> element within d.ditamap, the value puzzles is added to any existing values.

Example: How attributes cascade from one map to another

This section is non-normative.

In this scenario, attributes in one map cascade to a nested map.

Assume the following references in test.ditamap:
<map>
  <topicref href="a.ditamap" format="ditamap" toc="no"/>
  <mapref   href="b.ditamap" audience="developer"/>
  <mapref   href="c.ditamap#branch2" platform="myPlatform"/>
</map>
  • The map a.ditamap is treated as if toc="no" is specified on the root <map> element. This means that the topics that are referenced by a.ditamap do not appear in the navigation generated by test.ditamap, except for branches within the map that explicitly set toc="yes".
  • The map b.ditamap is treated as if audience="developer" is set on the root <map> element. If the @audience attribute is already set on the root <map> element within b.ditamap, the value "developer" is added to any existing values.
  • The element with id="branch2" within the map c.ditamap is treated as if platform="myPlatform" is specified on that element. If the @platform attribute is already specified on the element with id="branch", the valuemyPlatform is added to existing values.

Example: How the @cascade attribute affects attribute cascading

This section is non-normative.

In this scenario, the @cascade attribute is used to modify how metadata attributes cascade within a map.

Figure 1. Example of cascade="merge"
Consider the following code example:
<map audience="a b" cascade="merge">
     <topicref href="topic.dita" audience="c"/>
</map>

In this map, the cascade="merge" attribute instructs a processor to merge attribute values while cascading. With @audience specified on both the <map> element and the <topicref> element, the effective @audience attribute value for the reference to topic.dita is a b c.

Figure 2. Example of cascade="nomerge"
Consider the following code example:
<map audience="a b" cascade="nomerge">
     <topicref href="topic.dita" audience="c"/>
</map>

In this map, the cascade="nomerge" attribute instructs a processor not to merge attribute values while cascading. With @audience specified on both the <map> element and the <topicref> element, the effective @audience attribute value on the reference to topic.dita is not merged with the value from the map and remains c.

Figure 3. Example of changing the @cascade value within the map
Consider the following code example:
<map platform="a" product="x" cascade="merge">
  <topicref href="one.dita" platform="b" product="y">
    <topicref href="two.dita">
      <topicref href="three.dita" cascade="nomerge" product="z">
        <topicref href="four.dita"/>
      </topicref>
    </topicref>
  </topicref>
</map>

In this map, the @cascade attribute is set to merge at the map level but changes to nomerge on a topic reference.

  • For the topic reference to one.dita, cascade="merge" is specified. This results in an effective @platform value of a b and an effective @product value of x y.
  • The topic reference to two.dita does not specify any additional attributes. The effective values for the @platform and @product attributes are the same as those on the parent topic reference to one.dita. The effective value of of the @platform attribute is a b, and the effective value for the @product attribute is x y.
  • The topic reference to three.dita specifies cascade="nomerge", so attribute values from other elements do not merge with anything specified on the topic reference. The @platform attribute is not specified, so the effective value is a b, which still cascades from the parent element. The @product value does not merge with values from the parent, so the effective value is z.
  • The topic reference to four.dita does not specify any additional attributes. The effective values for the @platform and @product attributes are the same as those on the parent topic reference to three.dita. The effective value of of the @platform attribute is a b, and the effective value for the @product attribute is z.