<ditavalref>

The <ditavalref> element references a DITAVAL document that specifies filter conditions to be used when processing a map or map branch.

Processing expectations

When a <ditavalref> element is included in a map, the conditions in the referenced DITAVAL document are used to filter the elements in the branch. The branch includes the parent element that contains the <ditavalref> element, any child elements, and all resources that are referenced by the parent element or its children. While there is no technical restriction that forces <ditavalref> to appear before peer topic references, placing them first is considered a best practice and all examples in the specification will use this convention.

In the simple case, a map can use <ditavalref> as follows:
<map>
  <topicref href="sampleBranch.dita" audience="admin">
    <topicmeta>
      <navtitle>Navigation title for branch</navtitle>
    </topicmeta>
    <ditavalref href="conditions.ditaval"/>
    <topicref href="insideBranch.dita" platform="win linux mac"/>
  </topicref>
  <!-- Other branches not affected by conditions.ditaval -->
</map>
The filtering conditions specified in the conditions.ditaval file apply to the following:
  • The <topicref> element that references sampleBranch.dita and all child elements: <topicmeta>, <navtitle>, and <topicref> elements
  • The sampleBranch.dita topic
  • The insideBranch.dita topic

When more than one <ditavalref> element is specified in the same branch at the same level, the effective result is one copy of the branch for each <ditavalref> element. If the example above contains a reference to otherConditions.ditaval as a peer to the existing <ditavalref> element, the rendered version of this map would reflect two copies of "Sample branch", each reflecting the conditions that are specified in the corresponding DITAVAL document. One copy is created using the conditions in conditions.ditaval, while the other copy uses the conditions from otherConditions.ditaval. Map authors can use specific elements from the DITAVAL reference domain to indicate how resources are renamed, or processors can recover from naming collisions by using an alternate naming scheme. See Limitations below for more information.

If DITAVAL conditions are specified at multiple levels within a single branch, "exclude" conditions that are specified at a higher level take precedence. In the following branch, assume alternate rules are specified for the condition audience="novice", with the value set to "exclude" in highLevel.ditaval and "include" in lowLevel.ditaval. In that case, the "exclude" condition specified in highLevel.ditaval takes precedence and so applies to the entire branch. This is true regardless of how the "exclude" condition is specified within highLevel.ditaval. That is, there might be a specific rule for audience="novice"; alternatively, the @audience attribute might be set to "exclude" by default, with no specific condition specified for the value audience="novice".
<topicref href="ancestor.dita">
  <ditavalref href="highLevel.ditaval"/>
  <topicref href="descendent.dita">
    <ditavalref href="lowLevel.ditaval"/>
    <!-- Other topicrefs -->
  </topicref>
</topicref>

If a <ditavalref> element is used that does not specify the @href attribute, the element is still processed but no additional filtering is applied. This can be used to create an unfiltered copy of a map branch alongside other filtered copies; other aspects of the <ditavalref> (such as any specified key scope or modified resource name) will still be applied to the branch.

Limitations

Draft comment: robander
This topic overall has far more processing information than seems appropriate for an element reference topic; there is likely a lot of overlap / duplication of information contained in the Branch Filtering section of the arch spec. Most of this information should be moved there, likely including the full set of Limitations.

Draft comment: robander
TO RESOLVE 13 May 2026: Needs an editing pass, moving most of the architectural info into the "Branch filtering" section of the arch spec

The following limitations apply when using the <ditavalref> element; these limitations cannot be enforced in a DTD or other XML grammar files.

When the use of the <ditavalref> element results in multiple copies of a branch, resource names within that branch can be controlled with sub-elements of the effective <ditavalref>. For situations where resource names are relevant, it is an error condition for multiple <ditavalref> elements to result in conflicting resource names for different content. For example, the following map fragment would result in two distinct copies of the c.dita topic with the same file name:
<topicref href="c.dita">
  <ditavalref href="one.ditaval"/>
  <ditavalref href="two.ditaval"/>
</topicref>
Processors MAY recover by using an alternate naming scheme for the conflicting copies.
Draft comment: Kristen J Eberlein 15 May 2019

Need more information about what situation the processor is recovering from ...

Draft comment: robander
For the above, it would be recovering from a map that instructs it to create two files of the same name, with different filter conditions applied.
Draft comment: robander
TO RESOLVE 13 May 2026: To add when moving the content into arch spec, this rule should be in the arch spec

Specialization hierarchy

The <ditavalref> element is specialized from <topicref>. It is defined in the DITAVAL-reference domain module.

Content model

<ditavalmeta>?

Not contained by any element.

Optional <ditavalmeta>

Not contained by any element.

Inheritance

+ map/topicref ditavalref-d/ditavalref

The <ditavalref> element is specialized from <topicref>. It is defined in the ditavalref-domain module.

Attributes

The following attributes are available on this element: universal attributes (except for @conkeyref, which is removed for all elements in this domain), @format, @href, @impose-role, and @scope.

For this element:
  • The @format attribute has a default value of ditaval.
  • The @impose-role attribute has a fixed value of keeptarget.
  • The @href attribute specivies a reference to a DITAVAL document. If the @href attribute is unspecified, this <ditavalref> will not result in any new filtering behavior, but other aspects of the element are still evaluated.
  • The @processing-role attribute has a default value of resource-only.
Draft comment: robander
DITA 1.3 said that format MUST be ditaval, and that no value other than "resource-only" is valid for processing role. Should these be #FIXED in the grammar files?

Draft comment: robander
TO RESOLVE 13 May 2026: Can raise this at TC, but it's fine / low impact if we just keep the same definitions from 1.3 and don't make these fixed

The following attributes are available on this element: universal attributes (except for @conkeyref which is removed for all elements in this domain) and the attributes defined below.

@format (link-relationship attributes)
Specifies the format of the resource that is referenced. See The format attribute for detailed information on supported values and processing implications.
The @format attribute has a default value of ditaval.
@href (link-relationship attributes)
Specifies a reference to a resource. See The href attribute for detailed information on supported values and processing implications.
The @href attribute specivies a reference to a DITAVAL document. If the @href attribute is unspecified, this <ditavalref> will not result in any new filtering behavior, but other aspects of the element are still evaluated.
@impose-role
Specifies whether this element will impose its role on elements in a referenced map. The attribute is ignored if the target of the reference is not a map or branch of a map. The following values are valid:
keeptarget
The role of the current reference is not imposed on the target of the reference. This is the default for the unspecialized <topicref> element and for many convenience elements such as <keydef>.
impose
The role of the current reference is imposed on the target of the reference. For example, if a specialized topic reference <chapter> uses this value and references a map, a topic reference that resolves in place of the <chapter> will be treated as if it were a chapter.
-dita-use-conref-target
See Using the -dita-use-conref-target value for more information.

See The href attribute for detailed information on supported values and processing implications.

The @impose-role attribute has a fixed value of keeptarget.
@processing-role
The @processing-role attribute has a default value of resource-only.
@scope (link-relationship attributes)
Specifies the closeness of the relationship between the current document and the referenced resource. The following values are valid: local, peer, external, and -dita-use-conref-target.

See The scope attribute for detailed information on supported values and processing implications.

Example

This section is non-normative.

See Examples of branch filtering for several examples of the <ditavalref> element.