Cascading of roles from map to map

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 @class values should be replaced.

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. The @class attribute for <chapter> ("- map/topicref bookmap/chapter ") cascades to the top-level <topicref> element in the nested map, although it does not cascade any further.

Alternatively, the <mapref> element in the mapgroup domain 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.