Home
Architectural specification: All-inclusive edition
The architectural specification portion of the DITA specification outlines the framework of DITA. It contains an overview of DITA markup; addressing; processing; configuration, specialization, generalization, and constraints; as well as information about coding DITA grammar files.
DITA processing
DITA processing is affected by a number of factors, including attributes that indicate the set of vocabulary and constraint modules on which a DITA document depends; navigation; linking; content reuse (using direct or indirect addressing); conditional processing; branch filtering; chunking; and more. In addition, translation of DITA content is expedited through the use of the @dir, @translate, and @xml:lang attributes, and the <index-sort-as> element.
Branch filtering
The branch filtering mechanism enables map authors to set filtering conditions for specific branches of a map. This makes it possible for multiple conditional-processing profiles to be applied within a single publication.
Examples of branch filtering
The branch filtering examples illustrate the processing expectations for various scenarios that involve <ditavalref> elements. Processing examples use either before and after sample markup or expanded syntax that shows the equivalent markup without the <ditavalref> elements.
Example: Single <ditavalref> on a branch
A single <ditavalref> element can be used to supply filtering conditions for a branch.

Specification URIs
Notices
Introduction to DITA 1.3
The Darwin Information Typing Architecture (DITA) specification defines a set of document types for authoring and organizing topic-oriented information, as well as a set of mechanisms for combining, extending, and constraining document types.
Architectural specification: All-inclusive edition
The architectural specification portion of the DITA specification outlines the framework of DITA. It contains an overview of DITA markup; addressing; processing; configuration, specialization, generalization, and constraints; as well as information about coding DITA grammar files.
- Introduction to DITA
  The Darwin Information Typing Architecture (DITA) is an XML-based architecture for authoring, producing, and delivering topic-oriented, information-typed content that can be reused and single-sourced in a variety of ways. While DITA historically has been driven by the requirements of large-scale technical documentation authoring, management, and delivery, it is a standard that is applicable to any kind of publication or information that might be presented to readers, including interactive training and educational materials, standards, reports, business documents, trade books, travel and nature guides, and more.
- DITA markup
  Topics and maps are the basic building blocks of the Darwin Information Typing Architecture (DITA). Metadata attributes and values can be added to DITA topics and maps, as well as to elements within topics, to allow for conditional publishing and content reuse.
- DITA addressing
  DITA provides two addressing mechanisms. DITA addresses either are direct URI-based addresses, or they are indirect key-based addresses. Within DITA documents, individual elements are addressed by unique identifiers specified on the @id attribute. DITA defines two fragment-identifier syntaxes; one is the full fragment-identifier syntax, and the other is an abbreviated fragment-identifier syntax that can be used when addressing non-topic elements from within the same topic.
- DITA processing
  DITA processing is affected by a number of factors, including attributes that indicate the set of vocabulary and constraint modules on which a DITA document depends; navigation; linking; content reuse (using direct or indirect addressing); conditional processing; branch filtering; chunking; and more. In addition, translation of DITA content is expedited through the use of the @dir, @translate, and @xml:lang attributes, and the <index-sort-as> element.
  - Navigation
    DITA includes markup that processors can use to generate reader navigation to or across DITA topics. Such navigation behaviors include table of contents (TOCs) and indexes.
  - Content reference (conref)
    The DITA conref attributes provide mechanisms for reusing content. DITA content references support reuse scenarios that are difficult or impossible to implement using other XML-based inclusion mechanisms like XInclude and entities. Additionally, DITA content references have rules that help ensure that the results of content inclusion remain valid after resolution
  - Conditional processing (profiling)
    Conditional processing, also known as profiling, is the filtering or flagging of information based on processing-time criteria.
  - Branch filtering
    The branch filtering mechanism enables map authors to set filtering conditions for specific branches of a map. This makes it possible for multiple conditional-processing profiles to be applied within a single publication.
    - Overview of branch filtering
      Maps or map branches can be filtered by adding a <ditavalref> element that specifies the DITAVAL document to use for that map or map branch.
    - Branch filtering: Single condition set for a branch
      Using a single <ditavalref> element as a child of a map or map branch indicates that the map or map branch must be conditionally processed using the rules specified in the referenced DITAVAL document.
    - Branch filtering: Multiple condition sets for a branch
      Using multiple <ditavalref> elements as the children of a map or map branch indicates that the map or map branch must be conditionally processed using the rules that are specified in the referenced DITAVAL documents.
    - 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.
    - Branch filtering: Implications of processing order
      Because the branch filtering process can result in new or renamed keys, key scopes, or URIs, the full effects of the branch filtering process MUST be calculated by processors before they construct the effective map and key scope structure.
    - Examples of branch filtering
      The branch filtering examples illustrate the processing expectations for various scenarios that involve <ditavalref> elements. Processing examples use either before and after sample markup or expanded syntax that shows the equivalent markup without the <ditavalref> elements.
      - Example: Single <ditavalref> on a branch
        A single <ditavalref> element can be used to supply filtering conditions for a branch.
      - Example: Multiple <ditavalref> elements on a branch
        Multiple <ditavalref> elements can be used on a single map branch to create multiple distinct copies of the branch.
      - Example: Single <ditavalref> as a child of <map>
        Using a <ditavalref> element as a direct child of the <map> element is equivalent to setting global filtering conditions for the map.
      - Example: Single <ditavalref> in a reference to a map
        Using a <ditavalref> element in a reference to a map is equivalent to setting filtering conditions for the referenced map.
      - Example: Multiple <ditavalref> elements as children of <map> in a root map
        Using multiple instances of the <ditavalref> element as direct children of the <map> element in a root map is equivalent to setting multiple sets of global filtering conditions for the root map.
      - Example: Multiple <ditavalref> elements in a reference to a map
        Using multiple instances of the <ditavalref> element in a reference to a map is equivalent to referencing that map multiple times, with each reference nesting one of the <ditavalref> elements.
      - Example: <ditavalref> within a branch that already uses <ditavalref>
        When a branch is filtered because a <ditavalref> element is present, another <ditavalref> deeper within that branch can supply additional conditions for a subset of the branch.
      - Example: <ditavalref> error conditions
        It is an error condition when multiple, non-equivalent copies of the same file are created with the same resource name.
  - Chunking
    Content can be chunked (divided or merged into new output documents) in different ways for the purposes of delivering content and navigation. For example, content best authored as a set of separate topics might need to be delivered as a single Web page. A map author can use the @chunk attribute to split up multi-topic documents into component topics or to combine multiple topics into a single document as part of output processing.
  - Translation and localization
    DITA has features that facilitate preparing content for translation and working with multilingual content, including the @xml:lang attribute, the @dir attribute, and the @translate attribute. In addition, the <sort-as> and <index-sort-as> elements provide support for sorting in languages in which the correct sorting of an element requires text that is different from the base content of the element.
  - Processing documents with different values of the @domains attribute
    When DITA elements are copied from one document to another, processors need to determine the validity of the copied elements. This copying might occur as the result of a content reference (conref) or key reference (keyref), or it might occur in the context of an author editing a DITA document.
  - Sorting
    Processors can be configured to sort elements. Typical processing includes sorting glossary entries, lists of parameters or reference entries in custom navigation structures, and tables based on the contents of cells in specific columns or rows.
- Configuration, specialization, generalization, and constraints
  The extension facilities of DITA allow existing vocabulary and constraint modules to be combined to create specific DITA document types. Vocabulary modules also can be specialized to meet requirements that are not satisfied by existing markup.
- Coding practices for DITA grammar files
  This section collects all of the rules for creating modular DTD, RELAX NG, or XML Schema grammar files to represent DITA document types, specializations, and constraints.
- Technical content specializations
  This section contains information about the technical content specializations. It includes a summary of the document types and domains, as well as information about how the technical content specializations support authoring troubleshooting information.
- Learning and training specializations
  The section contains information about the learning and training specializations: Challenges faced by developers of instructional content; use cases; objectives of the specializations; information about the reusable learning-objects approach to learning and training content; summary of the topic types and domains; and more.
Language reference: All-inclusive edition
The language reference portion of the DITA specification contains a topic for each DITA element. The topic defines the element, its inheritance hierarchy, and provides examples of usage. This portion of the DITA specification also includes information about DITA attributes.
Conformance
Conformance to the DITA specification allows documents and document types that are used with different processors or different versions of a processor to produce the same or similar results with little or no reimplementation or modification.
Acknowledgments
(Non-normative) Many members of the OASIS DITA Technical Committee participated in the creation of this specification and are gratefully acknowledged.
Non-normative information
This section contains non-normative information, including topics about new features in DITA 1.3 and migrating from DITA 1.2 to DITA 1.3.
Content models for learning and training package
For each element in the learning and training package, this section presents the content model and a list of parent elements that can contain that element.

Example: Single `<ditavalref>` on a branch

A single <ditavalref> element can be used to supply filtering conditions for a branch.

Consider the following DITA map and the DITAVAL file that is referenced from the <ditavalref> element:

Figure 1. input.ditamap:


<map>
  <topicref href="intro.dita"/>
  <topicref href="install.dita">
    <ditavalref href="novice.ditaval"/>
    <topicref href="do-stuff.dita"/>
    <topicref href="advanced-stuff.dita" audience="admin"/>
    <!-- more topics -->
  </topicref>
  <!-- Several chapters worth of other material -->
</map>

Figure 2. Contents of novice.ditaval

<val>
  <prop att="audience" val="novice" action="include"/>
  <prop att="audience" val="admin" action="exclude"/>
</val>

When this content is published, the following processing occurs:

The first topic (intro.dita) does not use any of the conditions that are specified in novice.ditaval. It is published normally, potentially using other DITAVAL conditions that are specified externally.
The second topic (install.dita) is filtered using any external conditions as well as the conditions that are specified in novice.ditaval.
The third topic (do-stuff.dita) is filtered using any external conditions as well as the conditions that are specified in novice.ditaval.
The fourth topic (advanced-stuff.dita) is removed from the map entirely, because it is filtered out with the conditions that are specified for the branch.

In this example, no resources are renamed based on the <ditavalref> processing.

Note:

In cases where the original resource names map directly to names or anchors in a deliverable, the absence of renaming ensures that external links to those topics are stable regardless of whether a DITAVAL document is used.