Using 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.

The DITAVALref domain defines four elements to control URI and key scope values within filtered map branches.

<dvrResourcePrefix>
The <dvrResourcePrefix> element specifies the prefix to use when constructing the effective file names or resource IDs of the resources that are referenced from within the map branch that is implied by the ancestor <ditavalref> element. This enables a map author to specify a prefix that is added to the start of resource names for each resource in the branch.
<dvrResourceSuffix>
The <dvrResourceSuffix> element specifies the prefix to use when constructing the effective file names or resource IDs of the resources that are referenced from within the map branch that is implied by the ancestor <ditavalref> element. This 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>
The <dvrKeyscopePrefix> element specifies the prefix to use when constructing the effective key scope names for the map branch that is implied by the ancestor <ditavalref> element. This 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>
The <dvrKeyscopeSuffix> element specifies the suffix to use when constructing the effective key scope names for the map branch that is implied by the ancestor <ditavalref> element. This 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 (non-normative):
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.