Cascading of roles from map to map

When specialized <topicref> elements, such as <chapter> or <mapref>, reference a map, they typically imply a semantic role for the referenced content.

The semantic role reflects the @class hierarchy of the referencing <topicref> element. It is equivalent to having the @class attribute from the referencing <topicref> cascade to the top-level <topicref> elements in the referenced map. Although this cascade behavior is not universal, there are general guidelines for when a role based on the @class attribute cascades.

When a <topicref> element or a specialization of a <topicref> element references a DITA resource, it defines a role for that resource. In some cases this role is straightforward, such as when a <topicref> element references a DITA topic (giving it the already known role of "topic"), or when a <mapref> element references a DITA map (giving it the role of "DITA map").

Unless otherwise instructed, a specialized <topicref> element that references a map supplies a role for the referenced content. This means that, in effect, the @class attribute of the referencing element cascades to top-level topicref elements in the referenced map. In situations where this should not happen—such as all elements from the mapgroup domain—the non-default behavior should be clearly specified.

For example, when a <chapter> element from the bookmap specialization references a map, it supplies a role of "chapter" for each top-level <topicref> element in the referenced map. When the <chapter> element references a branch in another map, it supplies a role of "chapter" for that branch. In effect, the @class attribute for <chapter> ("- map/topicref bookmap/chapter ") cascades to the top-level <topicref> elements in the nested map, although it does not cascade any further.

Because the <mapref> element is a convenience element, the top-level <topicref> elements in the map referenced by a <mapref> element MUST NOT be processed as if they are <mapref> elements. The @class attribute from the <mapref> element ("+ map/topicref mapgroup-d/mapref ") does not cascade to the referenced map.

In some cases, preserving the role of the referencing element might result in out-of-context content. For example, a <chapter> element that references a bookmap might pull in <part> elements that contain nested <chapter> elements. Treating the <part> element as a <chapter> will result in a chapter that nests other chapters, which is not valid in bookmap and might not be understandable by processors. The result is implementation specific. Processors MAY choose to treat this as an error, issue a warning, or simply assign new roles to the problematic elements.