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 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.
Indirect key-based addressing
DITA keys provide an alternative to direct addressing. The key reference mechanism provides a layer of indirection so that resources (for example, URIs, metadata, or variable text strings) can be defined at the DITA map level instead of locally in each topic.
Examples of keys
This section of the specification contains examples and scenarios. They illustrate a wide variety of ways that keys can be used.
Examples: Key definition
The <topicref> element, and any specialization of <topicref> that allows the @keys attribute, can be used to define keys.

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.
  - ID attribute
    The @id attribute assigns an identifier to DITA elements so that the elements can be referenced.
  - DITA linking
    DITA supports many different linking elements, but they all use the same set of attributes to describe relationships between content.
  - URI-based (direct) addressing
    Content reference and link relationships can be established from DITA elements by using URI references. DITA uses URI references in @href, @conref, and other attributes for all direct addressing of resources.
  - Indirect key-based addressing
    DITA keys provide an alternative to direct addressing. The key reference mechanism provides a layer of indirection so that resources (for example, URIs, metadata, or variable text strings) can be defined at the DITA map level instead of locally in each topic.
    - Core concepts for working with keys
      The concepts described below are critical for a full understanding of keys and key processing.
    - Key scopes
      Key scopes enable map authors to specify different sets of key definitions for different map branches.
    - Using keys for addressing
      For topic references, image references, and other link relationships, resources can be indirectly addressed by using the @keyref attribute. For content reference relationships, resources can be indirectly addressed by using the @conkeyref attribute.
    - Addressing keys across scopes
      When referencing key definitions that are defined in a different key scope, key names might need to be qualified with key scope names.
    - Cross-deliverable addressing and linking
      A map can use scoped keys to reference keys that are defined in a different root map. This cross-deliverable addressing can support the production of deliverables that contain working links to other deliverables.
    - Processing key references
      Key references can resolve as links, as text, or as both. Within a map, they also can be used to create or supplement information on a topic reference. This topic covers information that is common to all key processing, regardless of how the key is used.
    - Processing key references for navigation links and images
      Keys can be used to create or redirect links and cross references. Keys also can be used to address resources such as images or videos. This topic explains how to evaluate key references on links and cross references to determine a link target.
    - Processing key references on <topicref> elements
      While <topicref> elements are used to define keys, they also can reference keys that are defined elsewhere. This topic explains how to evaluate key references on <topicref> elements and its specializations.
    - Processing key references to generate text or link text
      Key references can be used to pull text from the key definition. This topic explains how to generate text from a key definition, regardless of whether the key reference also results in a link.
    - Examples of keys
      This section of the specification contains examples and scenarios. They illustrate a wide variety of ways that keys can be used.
      - Examples: Key definition
        The <topicref> element, and any specialization of <topicref> that allows the @keys attribute, can be used to define keys.
      - Examples: Key definitions for variable text
        Key definitions can be used to store variable text, such as product names and user-interface labels. Depending on the key definition, the rendered output might have a link to a related resource.
      - Example: Scoped key definitions for variable text
        Scoped key definitions can be used for variable text. This enables you to use the same DITA topic multiple times in a DITA map, and in each instance the variable text can resolve differently.
      - Example: Duplicate key definitions within a single map
        In this scenario, a DITA map contains duplicate key definitions. How a processor finds the effective key definition depends on document order and the effect of filtering applied to the key definitions.
      - Example: Duplicate key definitions across multiple maps
        In this scenario, the root map contains references to two submaps, each of which defines the same key. The effective key definition depends upon the document order of the direct URI references to the maps.
      - Example: Key definition with key reference
        When a key definition also specifies a key reference, the key reference must also be resolved in order to determine the effective resources bound to that key definition.
      - Example: References to scoped keys
        You can address scoped keys from outside the key scope in which the keys are defined.
      - Example: Key definitions in nested key scopes
        In this scenario, the root map contains nested key scopes, each of which contain duplicate key definitions. The effective key definition depends on key-scope precedence rules.
      - Example: Link redirection
        This scenario outlines how different authors can redirect links to a common topic by using key definitions. This could apply to <xref>, <link>, or any elements (such as <keyword> or <term>) that become navigation links.
      - Example: Link modification or removal
        This scenario outlines how different authors can effectively remove or modify a <link> element in a shared topic.
      - Example: Links from <term> or <keyword> elements
        The @keyref attribute enables authors to specify that references to keywords or terms in a DITA topic can be rendered as a link to an associated resource.
      - Example: conref redirection
        The @conkeyref attribute enables authors to share DITA topics that reuse content. It also enables map authors to specify different key definitions for common keys.
      - Example: Key scopes and omnibus publications
        Key scopes enable you to create omnibus publications that include multiple submaps that define the same key names for common items, such as product names or common topic clusters.
      - Example: How key scopes affect key precedence
        For purposes of key definition precedence, the scope-qualified key definitions from a child scope are considered to occur at the location of the scope-defining element within the parent scope.
      - Example: Keys and collaboration
        Keys enable authors to collaborate and work with evolving content with a minimum of time spent reworking topic references.
- 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.
- 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.

Examples: Key definition

The <topicref> element, and any specialization of <topicref> that allows the @keys attribute, can be used to define keys.

In the following example, a <topicref> element is used to define a key; the <topicref> element also contributes to the navigation structure.

<map>
  <!--... -->
  <topicref keys="apple-definition" href="apple-gloss-en-US.dita" />
  <!--... -->
</map>

The presence of the @keys attribute does not affect how the <topicref> element is processed.

In the following example, a <keydef> element is used to define a key.

<map>
  <!--... -->
  <keydef keys="apple-definition" href="apple-gloss-en-US.dita"/>
  <!--... -->
</map>

Because the <keydef> element sets the default value of the @processing-role attribute to "resource-only", the key definition does not contribute to the map navigation structure; it only serves as a key definition for the key name "apple-definition".