Branch filtering: Impact on resource and key names

When map branches are cloned by a processor in order to support multiple condition sets, processors must manage conflicting resource and key names. The ditavalref domain includes metadata elements that authors can use to specify how resource and key names are renamed.

Note: While the processing controls that are described here are intended primarily for use with map branches that specify multiple condition sets, they also can be used with map branches that include only a single <ditavalref> element.

When a map branch uses multiple condition sets, processors create multiple effective copies of the branch to support the different conditions. This results in potential conflicts for resource names, key names, and key scopes. Metadata elements inside of the <ditavalref> element are available to provide control over these values, so that keys, key scopes, and URIs can be individually referenced within a branch.

For example, the following map branch specifies two DITAVAL documents:

<topicref href="productFeatures.dita" keys="features" keyscope="prodFeatures">
  <ditavalref href="novice.ditaval"/>
  <ditavalref href="admin.ditaval"/>
  <topicref href="newFeature.dita" keys="newThing"/>
</topicref>

In this case, the processor has two effective copies of productFeatures.dita and newFeature.dita. One copy of each topic is filtered using the conditions specified in novice.ditaval, and the other copy is filtered using the conditions specified in admin.ditaval. If an author has referenced a topic using keyref="features" or keyref="prodFeatures.features", there is no way for a processor to distinguish which filtered copy is the intended target.

Metadata elements in the DITAVAL reference domain

Metadata within the <ditavalref> element makes it possible to control changes to resource names and key scope names, so that each distinct filtered copy can be referenced in a predictable manner.

<dvrResourcePrefix>
Enables a map author to specify a prefix that is added to the start of resource names for each resource in the branch.
<dvrResourceSuffix>
Enables a map author to specify a suffix that is added to the end of resource names (before any extension) for each resource in the branch.
<dvrKeyscopePrefix>
Enables a map author to specify a prefix that is added to the start of key scope names for each key scope in the branch. If no key scope is specified for the branch, this can be used to establish a new key scope, optionally combined with a value specified in <dvrKeyscopeSuffix>.
<dvrKeyscopeSuffix>
Enables a map author to specify a suffix that is added to the end of key scope names for each key scope in the branch.

For example, the previous code sample can be modified as follows to create predictable resource names and key scopes for the copy of the branch that is filtered using the conditions that are specified in admin.ditaval.

<topicref href="productFeatures.dita" keys="features" keyscope="prodFeatures">
  <ditavalref href="novice.ditaval"/>
  <ditavalref href="admin.ditaval">
    <ditavalmeta>
      <dvrResourcePrefix>admin-</dvrResourcePrefix>
      <dvrKeyscopePrefix>adminscope-</dvrKeyscopePrefix>
    </ditavalmeta>
  </ditavalref>
  <topicref href="newFeature.dita" keys="newThing"/>
</topicref>

The novice branch does not use any renaming, which allows it to be treated as the default copy of the branch. As a result, when the topics are filtered using the conditions that are specified in novice.ditaval, the resource names and key names are unmodified, so that references to the original resource name and key name will resolve to topics in the novice copy of the branch. This has the following effect on topics that are filtered using the conditions specified in admin.ditaval:

  • The prefix admin- is added to the beginning of each resource name in the admin branch.
    • The resource productFeatures.dita becomes admin-productFeatures.dita
    • The resource newFeature.dita becomes admin-newFeature.dita
  • The prefix adminscope- is added to the existing key scope "prodFeatures".
    • The attribute value keyref="adminscope-prodFeatures.features" refers explicitly to the admin copy of productFeatures.dita
    • The attribute keyref="adminscope-prodFeatures.newThing" refers explicitly to the admin copy of newFeature.dita
Note: In general, the best way to reference a topic that will be modified based on branch filtering is to use a key rather than a URI. Key scopes and key names (including those modified based on the elements above) must be calculated by processors before other processing. This means that in the example above, a key reference to adminscope-prodFeatures.features will always refer explicitly to the instance of productFeatures.dita filtered against the conditions in admin.ditaval, regardless of whether a processor has performed the filtering yet. References that use the URI productFeatures.dita or admin-productFeatures.dita could resolve differently (or fail to resolve), as discussed in Branch filtering: Implications of processing order.

Renaming based on multiple <ditavalref> elements

It is possible for a branch with <ditavalref> already in effect to specify an additional <ditavalref>, where each <ditavalref> includes renaming metadata. When renaming, metadata on the <ditavalref> nested more deeply within the branch appears closer to the original resource or key name. For example:

<topicref href="branchParent.dita">
  <ditavalref href="parent.ditaval">
    <ditavalmeta>
      <dvrResourcePrefix>parentPrefix-</dvrResourcePrefix>
    </ditavalmeta>
  </ditavalref>
  <!-- additional topics or layers of nesting -->
  <topicref href="branchChild.dita">
    <ditavalref href="child.ditaval">
      <ditavalmeta>
        <dvrResourcePrefix>childPrefix-</dvrResourcePrefix>
      </ditavalmeta>
    </ditavalref>
  </topicref>
</topicref>

In this situation, the resource branchChild.dita is given a prefix based on both the reference to parent.ditaval and the reference to child.ditaval. The value "childPrefix-" is specified in the <ditavalref> that is nested more deeply within the branch, so it appears closer to the original resource name. The resource branchChild.dita would result in parentPrefix-childPrefix-branchChild.dita. Suffixes (if specified) would be added in a similar manner, resulting in a name like branchChild-childSuffix-parentSuffix.dita. Note that the hyphens are part of the specified prefix; they are not added automatically.

Handling resource name conflicts

It is an error if <ditavalref>-driven branch cloning results in multiple copies of a topic that have the same resolved name. Processors SHOULD report an error in such cases. Processors MAY recover by using an alternate naming scheme for the conflicting topics.

In rare cases, a single topic might appear in different branches that set different conditions, yet still produce the same result. For example, a topic might appear in both the admin and novice copies of a branch but not contain content that is tailored to either audience; in that case, the filtered copies would match. A processor MAY consider this form of equivalence when determining if two references to the same resource should be reported as an error.