DITA terminology and notation

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 may be preceded by @ to distinguish them from elements or surrounding text, for example, the @props or the @class attribute.
element types: Element names may be delimited with angle brackets (< and >) to distinguish them from surrounding text, for example, the <keyword> and 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."

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, and other useful information that are not formal requirements or rules that must be followed. The terms non-normative and informative are used interchangeably.

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

Basic DITA terminology

The following terminology is used to discuss basic DITA concepts:

DITA attribute type

An attribute type that is one of the following:

One of the base attribute types that are defined by the DITA specification
A specialization of the either the @base or @props attribute

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 types normally are implemented using DITA document-type shells.

DITA document-type shell

A set of DTD or XSD 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 one of the following:

One of the base element types that are defined by the DITA specification
A specialization of one of the base element types

A DITA element type is declared in exactly one vocabulary module. DITA element types may only exhibit attributes that are DITA attribute types.

map instance

An occurrence of a map type in a document.

map type

An element type that defines a set of relationships among topic instances. The map type provides the root element and, through the contained element types, the substructure for the map instances. The map substructure provides hierarchy, group, and matrix organization of references to topic instances.

structural type instance

An occurrence of a topic type or a map type in a document.

topic instance

An occurrence of a topic type in a document.

topic type

An element type that defines a complete unit of content. The topic type provides the root element for the topic and, through the contained element types, the substructure for the topic instances. The root element of the topic type is not necessarily the same as the root element of a document type; document types may nest multiple topic types and may also declare non-DITA wrapper elements as the root element for compatibility with other processes.

Specialization terminology

The following terminology is used to discuss DITA specialization:

base content model

The content model of a DITA element before specialization or the application of constraints or extensions.

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 may be preserved in the generalized instance, thus allowing the original specialized type to be recreated from the generalized instance.

restricted content model

For a DITA element type, a content model that has been restricted from the base content model for the element type by one or more of the following mechanisms:

Removing optional elements
Requiring optional elements
Ordering of unordered elements
Restricting repeatable (but optional) elements from repeating

Content models may be restricted through the use of constraint modules or through specialization.

selective domain extension

An extension that replaces an extension element with element types that are defined in an domain module, thus making the base type unavailable in the DITA document-type shell that configures the extension.

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.

specialization parent

For a given DITA element type, the most specialized of its ancestors in its specialization hierarchy.

specialized attribute type

An attribute type that is defined as a semantic refinement of another attribute type. The attribute type must be specialized from either the @base or @props attribute, and its range of permissible values must be a subset of or identical to the values allowed by the original attribute type.

specialized element type

An element type that is defined as a semantic refinement of an existing element type. The content allowed by the specialized element type must be a subset of or identical to the content allowed by the original element type. Within a DITA document, all specialized element types must be refinements of one of the base element types, with the exception of elements that are used in the context of <foreign> or <unknown> elements.

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 exactly one 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 set of element types or an attribute type that supports a specific subject or functional area. Element types or attribute types in a domain can be integrated with topic types or map types to enhance semantic support for particular kinds of content. For example, the structural type <topic> declares the <keyword> element; when integrated with a domain for describing user interfaces, new keyword specializations (such as <wintitle>) become available wherever <keyword> was allowed in the original structural type.
element domain module: A domain module that defines one or more element types for use within maps or topics.
map module: A structural module that defines a single map type.
structural module: A vocabulary module that defines exactly one top-level map type or topic type. Structural modules may also define specializations of elements from domain modules.
topic module: A structural module that defines a single top-level topic type.
vocabulary module: A uniquely-named unit of element type or attribute type declaration. There are two types of vocabulary modules: structural modules and domain modules. For a given map type, topic type, or domain, there is exactly one vocabulary module that defines it.

The following figure illustrates the relationship between a DITA document, its DITA document-type shell, and the various vocabulary modules that it uses.

Figure 1. Instances, modules, and declarations Shows the relationship between a DITA document, its DITA document-type shell, and the various document-type modules that it uses.

Shows the relationship between a DITA document, its DITA document-type shell, and the various document-type modules that it uses.

Linking and addressing terms

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

key name

An identifier defined by a value of the @keys attribute. A key is bound to one or more of the following items:

A resource addressed by the <topicref> element or a specialization of the <topicref> element
An element contained with the <topicmeta> element of the <topicref> element or a specialization of the<topicref> element

key definition

A <topicref> element or specialization of a <topicref> element that specifies the @keys attribute and defines one or more key names.

key resolution context

The root map that establishes the context for resolving key references. For a given key-resolution instance, there is at most one root map that defines the effective value of the key space, as determined by the key definition precedence rules..

key space

The effective set of unique key names that are defined by a given key resolution context. Within a given key resolution context, a key name has at most one binding.

referenced element

An element that is referenced by another DITA element. See also referencing element.

Example

The following code sample is from the 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 (a URI reference or a key reference).