DITA terminology and notation

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.

2.1.1 DITA terminology and notation