Vocabulary modules

Darwin Information Typing Architecture (DITA) Version 1.2

Vocabulary modules are atomic units of XML vocabulary definition (element types and attributes). A given DITA element type or attribute is declared in exactly one vocabulary module.

Vocabulary modules must reflect the implementation requirements defined in this specification for each recognized constraint mechanism. These requirements ensure that all vocabulary modules of a given type follow the same basic coding patterns for how their components are named and organized.

Vocabulary modules intended to be used outside of a narrowly-restricted context should have one or more associated globally-unique names (public IDs, URNs, or absolute URLs) by which modules can be referenced without regard to their local storage location.

There are three types of vocabulary module:
structural
A vocabulary module that defines exactly one top-level map or topic type. Structural modules may also define specializations of elements from domain modules. Structural modules are either topic modules or map modules.

A topic vocabulary module must define exactly one top-level topic type. It may define additional topic types that are then allowed to occur as subordinate topics within the top-level topic. However, such subordinate topic types may not be used as the root elements of conforming DITA documents. For example, a given top-level topic type may require the use of subordinate topic types that would only ever be meaningful in the context of their containing type and thus would never be candidates for standalone authoring or aggregation via maps. In that case, the subordinate topic type may be declared in the module for the top-level topic type that uses it. However, in most cases, potential subordinate topics should be defined in their own vocabulary modules.

A map vocabulary module must define exactly one element type that specializes map.

element domain
A vocabulary module that defines one or more element types that specialize element types used within maps or topics.
attribute domain
A vocabulary module that defines exactly one specialization of either the @base or @props attribute.

A given vocabulary module exists in an exclusive hierarchy relative to its ancestor modules. For example, the <concept> topic type is defined in the concept topic module and is itself derived from the topic topic module (that is, the topic-defining structural module that defines the topic type <topic>). Likewise, the <task> topic type is defined in the task topic module and is derived from the <topic> topic type. Thus the concept and task topic types are children of the <topic> topic type in the module hierarchy rooted at the <topic> topic vocabulary module.

All topic types must ultimately be specialized from <topic>. All map types must ultimately be specialized from <map>. Domain elements intended for use in topics must ultimately be specialized from elements defined in the topic module. Domain elements intended for use in maps must ultimately be specialized from elements defined by or used in the map module (maps share some element types with topics but no map-specific elements may be used within topics). Domain attributes must ultimately be specialized from either the @base or @props attribute.

Each vocabulary module has an associated short name, which is used to identify the module in @class and @domains attribute values. While module names need not be globally unique, module names must be unique within the scope of a given specialization hierarchy. The short name must be a valid XML name token.

For structural types, the module name must be the same as the root element. For example, "task" is the name of the structural vocabulary module whose root element is <task>. For domains, the name is assigned by the developer of the vocabulary module. By convention, domain names end with "-d" and are kept short; for example, "ui-d" for the user interface domain and "pr-d" for the programming domain.

When integrated into concrete document types, vocabulary modules may be further constrained through the use of constraint modules. See Constraints.