DITA terminology and notation

Darwin Information Typing Architecture (DITA) Version 1.3 Part 3: All-Inclusive Edition

Document
Darwin Information Typing Architecture (DITA) Version 1.3 Part 3: All-Inclusive Edition
Version
1.3
Author
OASIS DITA Technical Committee

The DITA specification uses specific notation and terms to define the components of the DITA standard.

Notation

The following conventions are used throughout the specification:
attribute types
Attribute names are preceded by @ to distinguish them from elements or surrounding text, for example, the props or the class attribute.
element types
Element names are delimited with angle brackets (< and >) to distinguish them from surrounding text, for example, the keyword or the prolog element.

In general, the unqualified use of the term map or topic can be interpreted to mean "a map element and any specialization of a map element " or "a topic element or any specialization of a topic element." Similarly, the unqualified use of an element type name (for example, p) can be interpreted to mean the element type or any specialization of the element type.

Normative and non-normative information

The DITA specification contains normative and non-normative information:
Normative information
Normative information is the formal portion of the specification that describes the rules and requirements that make up the DITA standard and which must be followed.
Non-normative information
Non-normative information includes descriptions that provide background, examples, notes, and other useful information that are not formal requirements or rules that must be followed.

All information in the specification should be considered normative unless it is an example, a note, an appendix, or is explicitly labeled as non-normative. The DITA specification contains examples to help clarify or illustrate specific aspects of the specification. Because examples are specific rather than general, they might not illustrate all aspects or be the only way to accomplish or implement an aspect of the specification. Therefore all examples are non-normative.

Basic DITA terminology

The following terminology is used to discuss basic DITA concepts:

DITA document
An XML document that conforms to the requirements of this specification. A DITA document MUST have as its root element one of the following elements:
  • map or a specialization of the map element
  • topic or a specialization of the topic element
  • dita, which cannot be specialized, but which allows documents with multiple sibling topics
DITA document type
A unique set of structural modules, domain modules, and constraint modules that taken together provide the XML element and attribute declarations that define the structure of DITA documents.
DITA document-type shell
A set of DTD, XSD, or RELAX NG declarations that implement a DITA document type by using the rules and design patterns that are included in the DITA specification. A DITA document-type shell includes and configures one or more structural modules, zero or more domain modules, and zero or more constraint modules. With the exception of the optional declarations for the dita element and its attributes, DITA document-type shells do not declare any element or attribute types directly.
DITA element
An XML element instance whose type is a DITA element type. DITA elements must exhibit a class attribute that has a value that conforms to the rules for specialization hierarchy specifications.
DITA element type
An element type that is either one of the base element types that are defined by the DITA specification, or a specialization of one of the base element types.
map instance
An occurrence of a map type in a DITA document.
map type
A map or a specialization of map that defines a set of relationships among topic instances.
structural type instance
An occurrence of a topic type or a map type in a DITA document.
topic instance
An occurrence of a topic type in a DITA document.
topic type
A topic or a specialization of topic that defines a complete unit of content.

Specialization terminology

The following terminology is used to discuss DITA specialization:

base type
An element or attribute type that is not a specialization. All base types are defined by the DITA specification.
extension element
Within a vocabulary module, an element type that can be extended, replaced, or constrained for use in a DITA document type.
generalization
The process by which a specialized element is transformed into a less-specialized ancestor element or a specialized attribute is transformed into a less-specialized ancestor attribute. The original specialization-hierarchy information can be preserved in the generalized instance; this allows the original specialized type to be recreated from the generalized instance.
specialization
(1) The act of defining new element or attribute types as a semantic refinement of existing element or attribute types
(2) An element or attribute type that is a specialization of a base type
(3) A process by which a generalized element is transformed into one of its more specialized element types or a generalized attribute is transformed into a more specialized attribute.
specialization hierarchy
The sequence of element or attribute types, from the most general to most specialized, from which a given element or attribute type is specialized. The specialization hierarchy for a DITA element is formally declared through its class attribute.
structural type
A topic type or map type.

DITA modules

The following terminology is used to discuss DITA modules:

attribute domain module
A domain module that defines a specialization of either the base or props attribute.
constraint module
A set of declarations that imposes additional constraints onto the element or attribute types that are defined in a specific vocabulary module.
domain module
A vocabulary module that defines a set of element types or an attribute type that supports a specific subject or functional area.
element domain module
A domain module that defines one or more element types for use within maps or topics.
structural module
A vocabulary module that defines a top-level map type or topic type.
vocabulary module
A set of element or attribute declarations.

Linking and addressing terms

The following terminology is used to discuss linking and addressing terms:

referenced element
An element that is referenced by another DITA element. See also referencing element.
Example
Consider the following code sample from a installation-reuse.dita topic. The step element that it contains is a referenced element; other DITA topics reference the step element by using the conref attribute.
<step id="run-startcmd-script">
	<cmd>Run the startcmd script that is applicable to your operating-system environment.</cmd>
</step>
referencing element
An element that references another DITA element by specifying an addressing attribute. See also referenced element and addressing attribute
Example
The following step element is a referencing element. It uses the conref attribute to reference a step element in the installation-reuse.dita topic.
<step conref="installation-reuse.dita#reuse/run-startcmd-script">
	<cmd/>
</step>
addressing attribute
An attribute, such as conref, conkeyref, keyref, and href, that specifies an address.

Terminology related to keys

The following terminology is used to discuss keys:

resource
For the purposes of keys and key resolution, one of the following:
  • An object addressed by URI
  • Metadata specified on a resource, such as a scope or format attribute
  • Text or metadata located within a topicmeta element
key
A name for a resource. See Using keys for addressing for more information.
key definition
A topicref element that binds one or more key names to zero or more resources.
key reference
An attribute that references a key, such as keyref or conkeyref.
key space
A list of key definitions that are used to resolve key references.
effective key definition
The definition for a key within a key space that is used to resolve references to that key. A key might have multiple definitions within a key space, but only one of those definitions is effective.
key scope
A map or section of a map that defines its own key space and serves as the resolution context for its key references.

Map terms

root map
The DITA map that is provided as input for a processor.
submap
A DITA map that is referenced with a scope attribute that evaluates as "local". The value of the scope attribute might be explicitly set, be defaulted, or cascade from another element.
peer map
A DITA map that is referenced with a scope attribute that evaluates as "peer". The value of the scope attribute might be explicitly set, be defaulted, or cascade from another element.
map branch
A topicref element or a specialization of topicref, along with any child elements and all resources that are referenced by the original element or its children.