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

Chapter 2: 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.

The all-inclusive edition also contains:

Information about the techical-content specializations, as well as a topic that provides an overview of the DITA elements that support documenting troubleshooting information
Information about the learning and training specializations, including 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; and a summary of the topic types and domains

2.2.1: 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 is designed for creating new document types and describing new information domains based on existing types and domains. The process for creating new types and domains is called specialization. Specialization enables the creation of specific, targeted XML grammars that can still use tools and design rules that were developed for more general types and domains; this is similar to how classes in an object-oriented system can inherit the methods of ancestor classes.

Because DITA topics are conforming XML documents, they can be readily viewed, edited, and validated using standard XML tools, although realizing the full potential of DITA requires using DITA-aware tools.

2.2.1.1: 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 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.2.1.2: Basic concepts

DITA has been designed to satisfy requirements for information typing, semantic markup, modularity, reuse, interchange, and production of different deliverable forms from a single source. These topics provide an overview of the key DITA features and facilities that serve to satisfy these requirements.

DITA topics: In DITA, a topic is the basic unit of authoring and reuse. All DITA topics have the same basic structure: a title and, optionally, a body of content. Topics can be generic or more specialized; specialized topics represent more specific information types or semantic roles, for example, <concept>, <task>, <reference>, or <learningContent>. See DITA topics for more information.
DITA maps: DITA maps are documents that organize topics and other resources into structured collections of information. DITA maps specify hierarchy and the relationships among the topics; they also provide the contexts in which keys are defined and resolved. DITA maps SHOULD have .ditamap as the file extension. See DITA maps for more information.
Information typing: Information typing is the practice of identifying types of topics, such as concept, reference, and task, to clearly distinguish between different types of information. Topics that answer different reader questions (How ...? What is ...?) can be categorized with different information types. The base information types provided by DITA specializations (for example, technical content, machine industry, and learning and training) provide starter sets of information types that can be adopted immediately by many technical and business-related organizations. See Information typing for more information.
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. See DITA addressing for more information.
Content reuse: The DITA @conref, @conkeyref, @conrefend, and @conaction attributes provide mechanisms for reusing content within DITA topics or maps. These mechanisms can be used both to pull and push content. See Content reuse for more information
Conditional processing: Conditional processing, also known as profiling, is the filtering or flagging of information based on processing-time criteria. See Conditional processing for more information.
Configuration: A document type shell is an XML grammar file that specifies the elements and attributes that are allowed in a DITA document. The document type shell integrates structural modules, domain modules, and constraint modules. In addition, a document type shell specifies whether and how topics can nest. See Configuration for more information.
Specialization: The specialization feature of DITA allows for the creation of new element types and attributes that are explicitly and formally derived from existing types. This facilitates interchange of conforming DITA content and ensures a minimum level of common processing for all DITA content. It also allows specialization-aware processors to add specialization-specific processing to existing base processing. See Specialization for more information.
Constraints: Constraint modules define additional constraints for vocabulary modules in order to restrict content models or attribute lists for specific element types, remove certain extension elements from an integrated domain module, or replace base element types with domain-provided, extension element types. See Constraints for more information.

2.2.1.3: File extensions

DITA uses certain file extensions for topics, maps, and conditional processing profiles.

Files that contain DITA content SHOULD use the following file extensions:

DITA topics

*.dita (preferred)
*.xml

DITA maps

*.ditamap

Conditional processing profiles

*.ditaval

2.2.1.4: Producing different deliverables from a single source

DITA is designed to enable the production of multiple deliverable formats from a single set of DITA content. This means that many rendition details are specified neither in the DITA specification nor in the DITA content; the rendition details are defined and controlled by the processors.

Like many XML-based applications for human-readable documentation, DITA supports the separation of content from presentation. This is necessary when content is used in different contexts, since authors cannot predict how or where the material that they author will be used. The following features and mechanisms enable users to produce different deliverable formats from a single source:

DITA maps: Different DITA maps can be optimized for different delivery formats. For example, you might have a book map for printed output and another DITA map to generate online help; each map uses the same content set.
Specialization: The DITA specialization facility enables users to create XML elements that can provide appropriate rendition distinctions. Because the use of specializations does not impede interchange or interoperability, DITA users can safely create the specializations that are demanded by their local delivery and rendition requirements, with a minimum of additional impact on the systems and business processes that depend on or use the content. While general XML practices suggest that element types should be semantic, specialization can be used to define element types that are purely presentational in nature. The highlighting domain is an example of such a specialization.
Conditional processing: Conditional processing makes it possible to have a DITA topic or map that contains delivery-specific content.
Content referencing: The conref mechanism makes it possible to construct delivery-specific maps or topics from a combination of generic components and delivery-context-specific components.
Key referencing: The keyref mechanism makes it possible to have key words be displayed differently in different deliverables. It also allows a single link to resolve to different targets in different deliverables.
@outputclass attribute: The @outputclass attribute provides a mechanism whereby authors can indicate specific rendition intent where necessary. Note that the DITA specification does not define any values for the @outputclass attribute; the use of the @outputclass attribute is processor specific.

While DITA is independent of any particular delivery format, it is a standard that supports the creation of human-readable content. As such, it defines some fundamental document components including paragraphs, lists, and tables. When there is a reasonable expectation that such basic document components be rendered consistently, the DITA specification defines default or suggested renderings.

2.2.2: 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 topics and maps are XML documents that conform to the XML specification. As such, they can be viewed, edited, validated, and processed with standard XML tools, although some DITA-specific features, such as content reference, key reference, and specialization require DITA-specific processing for full implementation and validation.

2.2.2.1: DITA topics

DITA topics are the basic units of DITA content and the basic units of reuse. Each topic contains a single subject. Topics might be of specific specialized information types, such as task, concept, or reference, or they might be generic, that is, without a specified information type.

2.2.2.1.1: The topic as the basic unit of information

In DITA, a topic is the basic unit of authoring and reuse. All DITA topics have the same basic structure: a title and, optionally, a body of content. Topics can be generic or more specialized; specialized topics represent more specific information types or semantic roles, for example, <concept>, <task>, <reference>, or <learningContent>.

DITA topics consist of content units that can be as generic as sets of paragraphs and unordered lists or as specific as sets of instructional steps in a procedure or cautions to be considered before a procedure is performed. Content units in DITA are expressed using XML elements and can be conditionally processed using metadata attributes.

Classically, a DITA topic is a titled unit of information that can be understood in isolation and used in multiple contexts. It should be short enough to address a single subject or answer a single question but long enough to make sense on its own and be authored as a self-contained unit. However, DITA topics also can be less self-contained units of information, such as topics that contain only titles and short descriptions and serve primarily to organize subtopics or links or topics that are designed to be nested for the purposes of information management, authoring convenience, or interchange.

DITA topics are used by reference from DITA maps. DITA maps enable topics to be organized in a hierarchy for publication. Large units of content, such as complex reference documents or book chapters, are created by nesting topic references in a DITA map. The same set of DITA topics can be used in any number of maps.

DITA topics also can be used and published individually; for example, one can represent an entire deliverable as a single DITA document that consists of a root topic and nested topics. This strategy can accommodate the migration of legacy content that is not topic-oriented; it also can accommodate information that is not meaningful outside the context of a parent topic. However, the power of DITA is most fully realized by storing each DITA topic in a separate XML document and using DITA maps to organize how topics are combined for delivery. This enables a clear separation between how topics are authored and stored and how topics are organized for delivery.

2.2.2.1.2: The benefits of a topic-based architecture

Topics enable the development of usable and reusable content.

While DITA does not require the use of any particular writing practice, the DITA architecture is designed to support authoring, managing, and processing of content that is designed to be reused. Although DITA provides significant value even when reuse is not a primary requirement, the full value of DITA is realized when content is authored with reuse in mind. To develop topic-based information means creating units of standalone information that are meaningful with little or no surrounding context.

By organizing content into topics that are written to be reusable, authors can achieve several goals:

Content is readable when accessed from an index or search, not just when read in sequence as part of an extended narrative. Since most readers do not read technical and business-related information from beginning to end, topic-oriented information design ensures that each unit of information can be read independently.
Content can be organized differently for online and print delivery. Authors can create task flows and concept hierarchies for online delivery and create a print-oriented hierarchy to support a narrative content flow.
Content can be reused in different collections. Since a topic is written to support random access (as by search), it should also be understandable when included as part of various product deliverables. Topics permit authors to refactor information as needed, including only the topics that apply to each unique scenario.
Content is more manageable in topic form whether managed as individual files in a traditional file system or as objects in a content management system.
Content authored in topics can be translated and updated more efficiently and less expensively than information authored in larger or more sequential units.
Content authored in topics can be filtered more efficiently, encouraging the assembly and deployment of information subsets from shared information repositories.

Topics written for reuse should be small enough to provide opportunities for reuse but large enough to be coherently authored and read. When each topic is written to address a single subject, authors can organize a set of topics logically and achieve an acceptable narrative content flow.

2.2.2.1.3: Disciplined, topic-oriented writing

Topic-oriented writing is a disciplined approach to writing that emphasizes modularity and reuse of concise units of information: topics. Well-designed DITA topics can be reused in many contexts, as long as writers are careful to avoid unnecessary transitional text.

Conciseness and appropriateness

Readers who are trying to learn or do something quickly appreciate information that is written in a structure that is easy to follow and contains only the information needed to complete that task or grasp a fact. Recipes, encyclopedia entries, car repair procedures--all serve up a uniquely focused unit of information. The topic contains everything required by the reader.

Locational independence

A well-designed topic is reusable in other contexts to the extent that it is context free, meaning that it can be inserted into a new document without revision of its content. A context-free topic avoids transitional text. Phrases like "As we considered earlier ..." or "Now that you have completed the initial step ..." make little sense if a topic is reused in a new context in which the relationships are different or no longer exist. A well-designed topic reads appropriately in any new context because the text does not refer the reader outside the topic.

Navigational independence

Most print publications or web pages are a mixture of content and navigation. Internal links lead a reader through a sequence of choices as he or she navigates through a website. DITA supports the separation of navigation from content by assembling independent topics into DITA maps. Nonetheless, writers might want to provide links within a topic to additional topics or external resources. DITA does not prohibit such linking within individual topics. The DITA relationship table enables links between topics and to external content. Since it is defined in the DITA map, it is managed independently of the topic content.

Links in the content are best used for cross-references within a topic. Links from within a topic to additional topics or external resources should be avoided because they limit the reusability of the topic. To link from a term or keyword to its definition, use the DITA keyref facility to avoid creating topic-to-topic dependencies that are difficult to maintain. See Key-based addressing.

2.2.2.1.4: Information typing

Information typing is the practice of identifying types of topics, such as concept, reference, and task, to clearly distinguish between different types of information. Topics that answer different reader questions (How ...? What is ...?) can be categorized with different information types. The base information types provided by DITA specializations (for example, technical content, machine industry, and learning and training) provide starter sets of information types that can be adopted immediately by many technical and business-related organizations.

Information typing has a long history of use in the technical documentation field to improve information quality. It is based on extensive research and experience, including Robert Horn's Information Mapping and Hughes Aircraft's STOP (Sequential Thematic Organization of Proposals) technique. Note that many DITA topic types are not necessarily closely connected with traditional Information Mapping.

Information typing is a practice designed to keep documentation focused and modular, thus making it clearer to readers, easier to search and navigate, and more suitable for reuse. Classifying information by type helps authors perform the following tasks:

Develop new information more consistently
Ensure that the correct structure is used for closely related kinds of information (retrieval-oriented structures like tables for reference information and simple sequences of steps for task information)
Avoid mixing content types, thereby losing reader focus
Separate supporting concept and reference information from tasks, so that users can read the supporting information if needed and ignore if it is not needed
Eliminate unimportant or redundant detail
Identify common and reusable subject matter

DITA currently defines a small set of well-established information types that reflects common practices in certain business domains, for example, technical communication and instruction and assessment. However, the set of possible information types is unbounded. Through the mechanism of specialization, new information types can be defined as specializations of the base topic type (<topic>) or as refinements of existing topics types, for example, <concept>, <task>, <reference>, or <learningContent>.

You need not use any of the currently-defined information types. However, where a currently-defined information type matches the information type of your content, the currently-defined information type should be used, either directly, or as a base for specialization. For example, information that is procedural in nature should use the task information type or a specialization of task. Consistent use of established information types helps ensure smooth interchange and interoperability of DITA content.

2.2.2.1.5: Generic topics

The element type <topic> is the base topic type from which all other topic types are specialized. All topics have the same basic structure.

For authors, typed content is preferred to support consistency in writing and presentation to readers. The generic topic type should only be used if authors are not trained in information typing or when a specialized topic type is inappropriate. The OASIS DITA standard provides several specialized topic types, including concept, task, and reference that are critical for technical content development.

For those pursuing specialization, new specialized topic types should be specialized from appropriate ancestors to meet authoring and output requirements.

2.2.2.1.6: Topic structure

All topics have the same basic structure, regardless of topic type: title, description or abstract, prolog, body, related links, and nested topics.

All DITA topics must have an XML identifier (the @id attribute) and a title. The basic topic structure consists of the following parts, some of which are optional:

Topic element: The topic element holds the required @id attribute and contains all other elements.
Title: The title contains the subject of the topic.
Alternate titles: Titles specifically for use in navigation or search. When not provided, the base title is used for all contexts.
Short description or abstract: A short description of the topic or a longer abstract with an embedded short description. The short description might be used both in topic content (as the first paragraph), in generated summaries that include the topic, and in links to the topic. Alternatively, the abstract lets you create more complex introductory content and uses an embedded short description element to define the part of the abstract that is suitable for summaries and link previews.; While short descriptions aren't required, they can make a dramatic difference to the usability of an information set and should generally be provided for all topics.
Prolog: The prolog is the container for topic metadata, such as change history, audience, product, and so on.
Body: The topic body contains the topic content: paragraphs, lists, sections, and other content that the information type permits.
Related links: Related links connect to other topics. When an author creates a link as part of a topic, the topic becomes dependent on the other topic being available. To reduce dependencies between topics and thereby increase the reusability of each topic, authors can use DITA maps to define and manage links between topics, instead of embedding links directly in each related topic.
Nested topics: Topics can be defined inside other topics. However, nesting requires special care because it can result in complex documents that are less usable and less reusable. Nesting might be appropriate for information that is first converted from desktop publishing or word processing files or for topics that are unusable independent from their parent or sibling topics.; The rules for topic nesting can be configured in a document-type shells. For example, the standard DITA configuration for concept topics only allows nested concept topics. However, local configuration of the concept topic type could allow other topic types to nest or disallow topic nesting entirely. In addition, the @chunk attribute enables topics to be equally re-usable regardless of whether they are separate or nested. The standard DITA configuration for ditabase document-type documents allows unrestricted topic nesting and can be used for holding sets of otherwise unrelated topics that hold re-usable content. It can also be used to convert DITA topics from non-DITA legacy source without first determining how individual topics should be organized into separate XML documents.

2.2.2.1.7: Topic content

The content of all topics, regardless of topic type, is built on the same common structures.

Topic body: The topic body contains all content except for that contained in the title or the short description/abstract. The topic body can be constrained to remove specific elements from the content model; it also can be specialized to add additional specialized elements to the content model. The topic body can be generic while the topic title and prolog are specialized.
Sections and examples: The body of a topic might contain divisions, such as sections and examples. They might contain block-level elements like titles and paragraphs and phrase-level elements like API names or text. It is recommend that sections have titles, whether they are entered directly into the <title> element or rendered using a fixed or default title.; Either body divisions or untitled sections or examples can be used to delimit arbitrary structures within a topic body. However, body divisions can nest, but sections and examples cannot contain sections.
<sectiondiv>: The <sectiondiv> element enables the arbitrary grouping of content within a section for the purpose of content reuse. The <sectiondiv> element does not include a title. Content that requires a title should use <section> or <example>.
<bodydiv>: The <bodydiv> element enables the arbitrary grouping of content within the body of a topic for the purpose of content reuse. The <bodydiv> element does not include a title. Content that requires a title should use <section> or <example>.
<div>: The <div> element enables the arbitrary grouping of content within a topic. The <div> element does not include a title. Content that requires a title should use <section> or <example> or, possibly, <fig>.
Block-level elements: Paragraphs, lists, figures, and tables are types of "block" elements. As a class of content, they can contain other blocks, phrases, or text, though the rules vary for each structure.
Phrases and keywords: Phrase level elements can contain markup to label parts of a paragraph or parts of a sentence as having special semantic meaning or presentation characteristics, such as <uicontrol> or <b>. Phrases can usually contain other phrases and keywords as well as text. Keywords can only contain text.
Images: Images can be inserted to display photographs, illustrations, screen captures, diagrams, and more. At the phrase level, they can display trademark characters, icons, toolbar buttons, and so forth.
Multimedia: The <object> element enables authors to include multimedia, such as diagrams that can be rotated and expanded. The <foreign> element enables authors to include media within topic content, for example, SVG graphics, MathML equations, and so on.

2.2.2.2: DITA maps

This topic collection contains information about DITA maps and the purposes that they serve. It also includes high-level information about DITA map elements, attributes, and metadata.

2.2.2.2.1: Definition of DITA maps

DITA maps are documents that organize topics and other resources into structured collections of information. DITA maps specify hierarchy and the relationships among the topics; they also provide the contexts in which keys are defined and resolved. DITA maps SHOULD have .ditamap as the file extension.

Maps draw on a rich set of existing best practices and standards for defining information models, such as hierarchical task analysis. They also support the definition of non-hierarchical relationships, such as matrices and groups, which provide a set of capabilities that has similarities to Resource Description Framework (RDF) and ISO topic maps.

DITA maps use <topicref> elements to reference DITA topics, DITA maps, and non-DITA resources, for example, HTML and TXT files. The <topicref> elements can be nested or grouped to create relationships among the referenced topics, maps, and non-DITA files; the <topicref> elements can be organized into hierarchies in order to represent a specific order of navigation or presentation.

DITA maps impose an architecture on a set of topics. Information architects can use DITA maps to specify what DITA topics are needed to support a given set of user goals and requirements; the sequential order of the topics; and the relationships that exist among those topics. Because DITA maps provide this context for topics, the topics themselves can be relatively context-free; they can be used and reused in multiple different contexts.

DITA maps often represent a single deliverable, for example, a specific Web site, a printed publication, or the online help for a product. DITA maps also can be subcomponents for a single deliverable, for example, a DITA map might contain the content for a chapter in a printed publication or the troubleshooting information for an online help system. The DITA specification provides specialized map types; book maps represent printed publications, subject scheme maps represent taxonomic or ontological classifications, and learning maps represent formal units of instruction and assessment. However, these map types are only a starter set of map types reflecting well-defined requirements.

DITA maps establish relationships through the nesting of <topicref> elements and the application of the @collection-type attribute. Relationship tables also can be used to associate topics with each other based on membership in the same row; for example, task topics can be associated with supporting concept and reference topics by placing each group in cells of the same row. During processing, these relationships can be rendered in different ways, although they typically result in lists of "Related topics" or "For more information" links. Like many aspects of DITA, the details about how such linking relationships are presented is determined by the DITA processor.

DITA maps also define keys and organize the contexts (key scopes ) in which key references are resolved.

2.2.2.2.2: Purpose of DITA maps

DITA maps enable the scalable reuse of content across multiple contexts. They can be used by information architects, writers, and publishers to plan, develop, and deliver content.

DITA maps support the following uses:

Defining an information architecture

Maps can be used to define the topics that are required for a particular audience, even before the topics themselves exist. DITA maps can aggregate multiple topics for a single deliverable.

Defining what topics to build for a particular output

Maps reference topics that are included in output processing. Information architects, authors, and publishers can use maps to specify a set of topics that are processed at the same time, instead of processing each topic individually. In this way, a DITA map can serve as a manifest or bill of materials.

Defining navigation

Maps can define the online navigation or table of contents for a deliverable.

Defining related links

Maps define relationships among the topics they reference. These relationships are defined by the nesting of elements in the DITA map, relationship tables, and the use of elements on which the @collection-type attribute is set. On output, these relationships might be expressed as related links or the hierarchy of a table of contents (TOC).

Defining an authoring context

The DITA map can define the authoring framework, providing a starting point for authoring new topics and integrating existing ones.

Defining keys and key scopes

Maps can define keys, which provide an indirect addressing mechanism that enhances portability of content. The keys are defined by <topicref> elements or specializations of <topicref> elements, such as <keydef>. The <keydef> element is a convenience element; it is a specialized type of a <topicref> element with the following attributes:

A required @keys attribute
A @processing-role attribute with a default value of "resource-only".

Maps also define the context or contexts for resolving key-based references, such as elements that specify the @keyref or @conkeyref attribute. Elements within a map structure that specify a @keyscope attribute create a new context for key reference resolution. Key references within such elements are resolved against the set of effective key definitions for that scope.

Specialized maps can provide additional semantics beyond those of organization, linking, and indirection. For example, the subjectScheme map specialization adds the semantics of taxonomy and ontology definition.

2.2.2.2.3: DITA map elements

A DITA map describes the relationships among a set of DITA topics. The DITA map and map-group domain elements organize topics into hierarchies, groups, and relationships; they also define keys.

A DITA map is composed of the following elements:

<map>

The <map> element is the root element of the DITA map.

<topicref>

The <topicref> elements are the basic elements of a map. A <topicref> element can reference a DITA topic, a DITA map, or a non-DITA resource. A <topicref> element also can have a title, short description, and the same kind of prolog-level metadata that is available in topics.

The <topicref> elements can be nested to create a hierarchy, which can be used to define a table of contents (TOC) for print output, online navigation, and parent/child links. Hierarchies can be annotated using the @collection-type attribute to define a particular type of relationship, such as a set of choices, a sequence, or a family. These collection types can affect link generation, and they might be interpreted differently for different outputs.

<reltable>

Relationship tables are defined with the <reltable> element. Relationship tables can be used to define relationships among DITA topics or among DITA topics and non-DITA resources. In a relationship table, the columns define common attributes, metadata, or information types (for example, task or troubleshooting) for the resources that are referenced in that column. The rows define relationships between the resources in different cells of the same row.

The <relrow>, <relcell>, <relheader>, and <relcolspec> elements are used to define the components of the relationship table. Relationships defined in the relationship table also can be further refined by using the @collection-type attribute.

<topicgroup>

The <topicgroup> element defines a group or collection outside of a hierarchy or relationship table. It is a convenience element that is equivalent to a <topicref> element without an @href attribute or navigation title. Groups can be combined with hierarchies and relationship tables, for example, by including a <topicgroup> element within a set of siblings in a hierarchy or within a table cell. The <topicref> elements so grouped can then share inherited attributes and linking relationships with no effect on the navigation or table of contents.

<topicmeta>

Most map-level elements, including the map itself, can contain metadata inside the <topicmeta> element. Metadata typically is applied to an element and its descendants.

<ux-window>

The <ux-window> element enables authors to define windowing information for the display of output topics that are appropriate to the delivery platform. Window management is important in user assistance and help system outputs, as well as for other hypertext and electronic delivery modes.

<topichead>

The <topichead> element provides a navigation title; it is a convenience element that is equivalent to a <topicref> element with a navigation title but no associated resource.

<anchor>

The <anchor> element provides an integration point that another map can reference in order to insert its navigation into the referenced map's navigation tree. For those familiar with Eclipse help systems, this serves the same purpose as the <anchor> element in that system. It might not be supported for all output formats.

<navref>

The <navref> element represents a pointer to another map which is preserved as a transcluding link in the result deliverable rather than resolved when the deliverable is produced. Output formats that support such linking can integrate the referenced resource when displaying the referencing map to an end user.

<keydef>

Enables authors to define keys. This element is a convenience element; it is a specialization of <topicref> that sets the default value of the @processing-role attribute to "resource-only". Setting the @processing-role attribute to resource-only ensures that the resource referenced by the key definition is not directly included in the navigation that is defined by the map.

<mapref>

Enables authors to reference an entire DITA map, including hierarchy and relationship tables. This element is a convenience element; it is a specialization of <topicref> that sets the default value of the @format attribute to "ditamap". The <mapref> element represents a reference from a parent map to a subordinate map.

<topicset>

Enables authors to define a branch of navigation in a DITA map so that it can be referenced from another DITA map.

<topicsetref>

Enables authors to reference a navigation branch that is defined in another DITA map.

<anchorref>

Enables authors to define a map fragment that is pushed to the location defined by an anchor.

2.2.2.2.4: DITA map attributes

DITA maps have unique attributes that are designed to control the way that relationships are interpreted for different output purposes. In addition, DITA maps share many metadata and linking attributes with DITA topics.

DITA maps often encode structures that are specific to a particular medium or output, for example, Web pages or a PDF document. Attributes, such as @deliveryTarget and @toc, are designed to help processors interpret the DITA map for each kind of output. Many of these attributes are not available in DITA topics; individual topics, once separated from the high-level structures and dependencies associated with a particular kind of output, should be entirely reusable regardless of the intended output format.

@collection-type

The @collection-type attribute specifies how the children of a <topicref> element relate to their parent and to each other. This attribute, which is set on the parent element, typically is used by processors to determine how to generate navigation links in the rendered topics. For example, a @collection-type value of "sequence" indicates that children of the specifying <topicref> element represent an ordered sequence of topics; processors might add numbers to the list of child topics or generate next/previous links for online presentation. This attribute is available in topics on the <linklist> and <linkpool> elements, where it has the same behavior. Where the @collection-type attribute is available on elements that cannot directly contain elements (such as <reltable> or <topicref>), the behavior of the attribute is reserved for future use.

@linking

By default, the relationships between the topics that are referenced in a map are reciprocal:

Child topics link to parent topics and vice versa.
Next and previous topics in a sequence link to each other.
Topics in a family link to their sibling topics.
Topics referenced in the table cells of the same row in a relationship table link to each other. A topic referenced within a table cell does not (by default) link to other topics referenced in the same table cell.

This behavior can be modified by using the @linking attribute, which enables an author or information architect to specify how a topic should participate in a relationship. The following values are valid:

linking="none": Specifies that the topic does not exist in the map for the purposes of calculating links.
linking="sourceonly": Specifies that the topic will link to its related topics but not vice versa.
linking="targetonly": Specifies that the related topics will link to it but not vice versa.
linking="normal": Default value. It specifies that linking will be reciprocal (the topic will link to related topics, and they will link back to it).

Authors also can create links directly in a topic by using the <xref> or <link> elements, but in most cases map-based linking is preferable, because links in topics create dependencies between topics that can hinder reuse.

Note that while the relationships between the topics that are referenced in a map are reciprocal, the relationships merely imply reciprocal links in generated output that includes links. The rendered navigation links are a function of the presentation style that is determined by the processor.

@toc

Specifies whether topics are excluded from navigation output, such as a Web site map or an online table of contents. By default, <topicref> hierarchies are included in navigation output; relationship tables are excluded.

@navtitle

Specifies a navigation title. This is a shorter version of the title that is used in the navigation only. By default, the @navtitle attribute is ignored; it serves only to help the DITA map author keep track of the title of the topic.

Note

The @navtitle attribute is deprecated in favor of the <navtitle> element. When both a <navtitle> element and a @navtitle attribute are specified, the <navtitle> element should be used.

@locktitle

If @locktitle is set to "yes", the <navtitle> element or @navtitle attribute is used if it is present. Otherwise, the <navtitle> element or @navtitle attribute is ignored and the navigation title is retrieved from the referenced file.

Note

The @navtitle attribute is deprecated in favor of the <navtitle> element. When both a <navtitle> element and a @navtitle attribute are specified, the <navtitle> element should be used.

@print

Specifies whether the topic should be included in printed output.

Note

Beginning with DITA 1.3, the @print attribute is deprecated. It is replaced with a conditional processing attribute: @deliveryTarget. See @deliveryTarget for more details.

@search

Specifies whether the topic should be included in search indexes.

@chunk

Specifies that the processor generates an interim set of DITA topics that are used as the input for the final processing. This can produce the following output results:

Multi-topic files are transformed into smaller files, for example, individual HTML files for each DITA topic.
Individual DITA topics are combined into a single file.

Specifying a value for the @chunk attribute on a <map> element establishes chunking behavior that applies to the entire map, unless overridden by @chunk attributes that are set on more specific elements in the DITA map. For a detailed description of the @chunk attribute and its usage, see Chunking.

@copy-to

In most situations, specifies whether a duplicate version of the topic is created when it is transformed. This duplicate version can be either literal or virtual. The value of the @copy-to attribute specifies the uniform resource identifier (URI) by which the topic can be referenced by a @conref attribute, <topicref> element, or <xref> element. The duplication is a convenience for output processors that use the URI of the topic to generate the base address of the output. The @keys and @keyref attributes provide an alternative mechanism; they enable references to topics in specific-use contexts.

The @copy-to attribute also can be used to specify the name of a new chunk when topics are being chunked; it also can be used to determine the name of the stub topic that is generated from a <topicref> element that contains a title but does not specify a target. In both of those cases, no duplicate version of the topic is generated.

For information on how the @copy-to attribute can be used with the @chunk attribute, see Chunking.

@processing-role

Specifies whether the topic or map referenced should be processed normally or treated as a resource that is only included in order to resolve key or content references.

processing-role="normal": The topic is a readable part of the information set. It is included in navigation and search results. This is the default value for the <topicref> element.
processing-role="resource-only": The topic should be used only as a resource for processing. It is not included in navigation or search results, nor is it rendered as a topic. This is the default value for the <keydef> element.

If the @processing-role attribute is not specified locally, the value cascades from the closest element in the containment hierarchy.

@cascade

Specifies whether the default rules for the cascading of metadata attributes in a DITA map apply. In addition to the following specified values, processors also MAY define additional values.

cascade="merge": The metadata attributes cascade; the values of the metadata attributes are additive. This is the processing default for the @cascade attribute and was the only defined behavior for DITA 1.2 and earlier.
cascade="nomerge": The metadata attributes cascade; however, they are not additive for <topicref> elements that specify a different value for a specific metadata attribute. If the cascading value for an attribute is already merged based on multiple ancestor elements, that merged value continues to cascade until a new value is encountered (that is, setting cascade="nomerge" does not undo merging that took place on ancestors).

For more information, see Example: How the @cascade attribute functions.

@keys

Specifies one or more key names.

@keyscope

Defines a new scope for key definition and resolution, and gives the scope one or more names. For more information about key scopes, see Indirect key-based addressing.

Attributes in the list above are used exclusively or primarily in maps, but many important map attributes are shared with elements in topics. DITA maps also use many of the following attributes that are used with linking elements in DITA topics, such as <link> and <xref>:

@format

@href

@keyref

@scope

@type

The following metadata and reuse attributes are used by both DITA maps and DITA topics:

@product, @platform, @audience, @otherprops, @rev, @status, @importance
@dir, @xml:lang, @translate
@id, @conref, @conrefend, @conkeyref, @conaction
@props and any attribute specialized from @props (such as @deliveryTarget)
@search

When new attributes are specialized from @props or @base as a domain, they can be incorporated into both map and topic structural types.

2.2.2.2.5: Examples of DITA maps

This section of the specification contains simple examples of DITA maps. The examples illustrate a few of the ways that DITA maps are used.

2.2.2.2.5.1: Example: DITA map that references a subordinate map

This example illustrates how one map can reference a subordinate map using either <mapref> or the basic <topicref> element.

The following code sample illustrates how a DITA map can use the specialized <mapref> element to reference another DITA map:

<map>
  <title>DITA work at OASIS</title>
  <topicref href="oasis-dita-technical-committees.dita">
    <topicref href="dita_technical_committee.dita"/>
    <topicref href="dita_adoption_technical_committee.dita"/>
  </topicref>
  <mapref href="oasis-processes.ditamap"/>
  <!-- ... -->
</map>

The <mapref> element is a specialized <topicref> intended to make it easier to reference another map; use of <mapref> is not required for this task. This map also could be tagged in the following way:

<map>
  <title>DITA work at OASIS</title>
  <topicref href="oasis-dita-technical-committees.dita">
    <topicref href="dita_technical_committee.dita"/>
    <topicref href="dita_adoption_technical_committee.dita"/>
  </topicref>
<topicref href="oasis-processes.ditamap" format="ditamap"/>
<!-- ... -->
</map>

With either of the above examples, during processing, the map is resolved in the following way:

<map>
  <title>DITA work at OASIS</title>
  <topicref href="oasis-dita-technical-committees.dita">
    <topicref href="dita_technical_committee.dita"/>
    <topicref href="dita_adoption_technical_committee.dita"/>
  </topicref>
  <!-- Contents of the oasis-processes.ditamap file -->
  <topicref href="oasis-processes.dita">
    <!-- ... -->
  </topicref>
  <!-- ... -->
</map>

2.2.2.2.5.2: Example: DITA map with a simple relationship table

This example illustrates how to interpret a basic three-column relationship table used to maintain links between concept, task, and reference material.

The following example contains the markup for a simple relationship table:

<map>
<!-- ... -->
<reltable>
  <relheader>
    <relcolspec type="concept"/>
    <relcolspec type="task"/>
    <relcolspec type="reference"/>
  </relheader>
  <relrow>
    <relcell>
      <topicref href="A.dita"/>
    </relcell>
    <relcell>
      <topicref href="B.dita"/>
    </relcell>
    <relcell>
      <topicref href="C1.dita"/>
      <topicref href="C2.dita"/>
    </relcell>
  </relrow>
</reltable>
</map>

A DITA-aware tool might represent the relationship table graphically:

type="concept"	type="task"	type="reference"
A	B	C1 C2

When the output is generated, the topics contain the following linkage:

A: Links to B, C1, and C2
B: Links to A, C1, and C2
C1, C2: Links to A and B

2.2.2.2.5.3: Example: How the @collection-type and @linking attributes determine links

In this scenario, a simple map establishes basic hierarchical and relationship table links. The @collection-type and @linking attributes are then added to modify how links are generated.

The following example illustrates how linkage is defined in a DITA map:

Simple linking example

<topicref href="A.dita" collection-type="sequence">
  <topicref href="A1.dita"/>
  <topicref href="A2.dita"/>
</topicref>
<reltable>
  <relrow>
    <relcell><topicref href="A.dita"/></relcell>
    <relcell><topicref href="B.dita"/></relcell>
  </relrow>
</reltable>

When the output is generated, the topics contain the following linkage. Sequential (next/previous) links between A1 and A2 are present because of the @collection-type attribute on the parent:

A: Links to A1, A2 as children; Links to B as related
A1: Links to A as a parent; Links to A2 as next in the sequence
A2: Links to A as a parent; Links to A1 as previous in the sequence
B: Links to A as related

The following example illustrates how setting the @linking attribute can change the default behavior:

Linking example with the @linking attribute

<topicref href="A.dita" collection-type="sequence">
  <topicref href="B.dita" linking="none"/>
  <topicref href="A1.dita"/>
  <topicref href="A2.dita"/>
</topicref>
<reltable>
  <relrow>
    <relcell><topicref href="A.dita"/></relcell>
    <relcell linking="sourceonly"><topicref href="B.dita"/></relcell>
  </relrow>
</reltable>

When the output is generated, the topics contain the following linkage:

A: Links to A1, A2 as children; Does not link to B as a child or related topic
A1: Links to A as a parent; Links to A2 as next in the sequence; Does not link to B as previous in the sequence
A2: Links to A as a parent; Links to A1 as previous in the sequence
B: Links to A as a related topic

2.2.2.2.5.4: Example: How the @cascade attribute functions

The following example illustrates how the @cascade attribute can be used to fine tune how the values for the @platform attribute apply to topics referenced in a DITA map.

Here a DITA map contains a collection of topics that apply to Windows, Linux, and Macintosh OS; it also contains a topic that is only applicable to users running the application on Linux.

<map product="PuffinTracker" platform="win linux mac" cascade="nomerge">
  <title>Puffin Tracking Software</title>
  <topicref href="intro.dita" navtitle="Introduction"/>
  <topicref href="setup.dita" navtitle="Setting up the product"/>
  <topicref href="linux-instructions.dita" navtitle="Linux instructions" platform="linux"/>
</map>

The values of the @platform attribute set at the map level cascade throughout the map and apply to the "Introduction" and "Setting up the product" topics. However, since the value of the @cascade attribute is set to "nomerge", the value of the @platform attribute for the "Linux instructions" topic does not merge with the values that cascade from above in the DITA map. The effective value of the @platform attribute for linux-instructions.dita is "linux".

The same results are produced by the following mark-up:

<map product="PuffinTracker" platform="win linux mac">
  <title>Puffin Tracking Software</title>
  <topicref href="intro.dita" navtitle="Introduction"/>
  <topicref href="setup.dita" navtitle="Setting up the product"/>
  <topicref href="linux-instructions.dita" navtitle="Linux instructions" platform="linux" cascade="nomerge"/>
</map>

2.2.2.3: Subject scheme maps and their usage

Subject scheme maps can be used to define controlled values and subject definitions. The controlled values can be bound to attributes, as well as element and attribute pairs. The subject definitions can contain metadata and provide links to more detailed information; they can be used to classify content and provide semantics that can be used in taxonomies and ontologies.

A DITA map can reference a subject scheme map by using a <mapref> element. Processors also MAY provide parameters by which subject scheme maps are referenced.

2.2.2.3.1: Subject scheme maps

Subject scheme maps use key definitions to define collections of controlled values and subject definitions.

Controlled values are keywords that can be used as values for attributes. For example, the @audience attribute can take a value that identifies the users that are associated with a particular product. Typical values for a medical-equipment product line might include "therapist", "oncologist", "physicist", and "radiologist". In a subject scheme map, an information architect can define a list of these values for the @audience attribute. Controlled values can be used to classify content for filtering and flagging at build time.

Subject definitions are classifications and sub-classifications that compose a tree. Subject definitions provide semantics that can be used in conjunction with taxonomies and ontologies. In conjunction with the classification domain, subject definitions can be used for retrieval and traversal of the content at run time when used with information viewing applications that provide such functionality.

Key references to controlled values are resolved to a key definition using the same precedence rules as apply to any other key. However, once a key is resolved to a controlled value, that key reference does not typically result in links or generated text.

2.2.2.3.2: Defining controlled values for attributes

Subject scheme maps can define controlled values for DITA attributes without having to define specializations or constraints. The list of available values can be modified quickly to adapt to new situations.

Each controlled value is defined using a <subjectdef> element, which is a specialization of the <topicref> element. The <subjectdef> element is used to define both a subject category and a list of controlled values. The parent <subjectdef> element defines the category, and the children <subjectdef> elements define the controlled values.

The subject definitions can include additional information within a <topicmeta> element to clarify the meaning of a value:

The <navtitle> element can provide a more readable value name.
The <shortdesc> element can provide a definition.

In addition, the <subjectdef> element can reference a more detailed definition of the subject, for example, another DITA topic or an external resource..

The following behavior is expected of processors:

Authoring tools SHOULD use these lists of controlled values to provide lists from which authors can select values when they specify attribute values.
Authoring tools MAY give an organization a list of readable labels, a hierarchy of values to simplify selection, and a shared definition of the value.
An editor MAY support accessing and displaying the content of the subject definition resource in order to provide users with a detailed explanation of the subject.
Tools MAY produce a help file, PDF, or other readable catalog to help authors better understand the controlled values.

Example: Controlled values that provide additional information about the subject

The following code fragment illustrates how a subject definition can provide a richer level of information about a controlled value:

<subjectdef keys="terminology" href="https://www.oasis-open.org/policies-guidelines/keyword-guidelines">
  <subjectdef keys="rfc2119" href="rfc-2119.dita">
    <topicmeta>
      <navtitle>RFC-2119 terminology</navtitle>
      <shortdesc>The normative terminology that the DITA TC uses for the DITA specification</shortdesc>
    </topicmeta>
  </subjectdef>
  <subjectdef keys="iso" href="iso-terminology.dita">
    <topicmeta>
      <navtitle>ISO keywords</navtitle>
      <shortdesc>The normative terminology used by some other OASIS technical committees</shortdesc>
    </topicmeta>
  </subjectdef>
</subjectdef>

The content of the <navtitle> and <shortdesc> elements provide additional information that a processor might display to users as they select attribute values or classify content. The resources referenced by the @href attributes provide even more detailed information; a processor might render clickable links as part of a user interface that implements a progressive disclosure strategy

2.2.2.3.3: Binding controlled values to an attribute

The controlled values defined in a subject scheme map can be bound to an attribute or an element and attribute pair. This affects the expected behavior for processors and authoring tools.

The <enumerationdef> element binds the set of controlled values to an attribute. Valid attribute values are those that are defined in the set of controlled values; invalid attribute values are those that are not defined in the set of controlled values. An enumeration can specify an empty <subjectdef> element. In that case, no value is valid for the attribute. An enumeration also can specify an optional default value by using the <defaultSubject> element.

If an enumeration is bound, processors SHOULD validate attribute values against the controlled values that are defined in the subject scheme map. For authoring tools, this validation prevents users from entering misspelled or undefined values. Recovery from validation errors is implementation specific.

The default attribute values that are specified in a subject scheme map apply only if a value is not otherwise specified in the DITA source or as a default value by the XML grammar.

To determine the effective value for a DITA attribute, processors check for the following in the order outlined:

An explicit value in the element instance
A default value in the XML grammar
Cascaded value within the document
Cascaded value from a higher level document to the document
A default controlled value, as specified in the <defaultSubject> element
A value set by processing rules

Example: Binding a list of controlled values to the @audience attribute

The following example illustrates the use of the <subjectdef> element to define controlled values for types of users. It also binds the controlled values to the @audience attribute:

<subjectScheme>
  <!-- Define types of users -->
  <subjectdef keys="users">
    <subjectdef keys="therapist"/>
    <subjectdef keys="oncologist"/>
    <subjectdef keys="physicist"/>
    <subjectdef keys="radiologist"/>
  </subjectdef>

  <!-- Bind the "users" subject to the @audience attribute.
       This restricts the @audience attribute to the following
       values: therapist, oncologist, physicist, radiologist -->
  <enumerationdef>
    <attributedef name="audience"/>
    <subjectdef keyref="users"/>
  </enumerationdef>
</subjectScheme>

When the above subject scheme map is used, the only valid values for the @audience attribute are "therapist", "oncologist", "physicist", and "radiologist". Note that "users" is not a valid value for the @audience attribute; it merely identifies the parent or container subject.

Example: Binding an attribute to an empty set

The following code fragment declares that there are no valid values for the @outputclass attribute.

<subjectScheme>
  <enumerationdef>
    <attributedef name="outputclass"/>
    <subjectdef/>
  </enumerationdef>
</subjectScheme>

2.2.2.3.4: Processing controlled attribute values

An enumeration of controlled values can be defined with hierarchical levels by nesting subject definitions. This affects how processors perform filtering and flagging.

The following algorithm applies when processors apply filtering and flagging rules to attribute values that are defined as a hierarchy of controlled values and bound to an enumeration:

If an attribute specifies a value in the taxonomy, and a DITAVAL or other categorization tool is configured with that value, the rule matches.
Otherwise, if the parent value in the taxonomy has a rule, that matches.
Otherwise, continue up the chain in the taxonomy until a matching rule is found.

The following behavior is expected of processors:

Processors SHOULD be aware of the hierarchies of attribute values that are defined in subject scheme maps for purposes of filtering, flagging, or other metadata-based categorization.
Processors SHOULD validate that the values of attributes that are bound to controlled values contain only valid values from those sets. (The list of controlled values is not validated by basic XML parsers.) If the controlled values are part of a named key scope, the scope name is ignored for the purpose of validating the controlled values.
Processors SHOULD check that all values listed for an attribute in a DITAVAL file are bound to the attribute by the subject scheme before filtering or flagging. If a processor encounters values that are not included in the subject scheme, it SHOULD issue a warning.

Example: A hierarchy of controlled values and conditional processing

The following example illustrates a set of controlled values that contains a hierarchy.

<subjectScheme>
  <subjectdef keys="users">
    <subjectdef keys="therapist">
      <subjectdef keys="novice-therapist"/>
      <subjectdef keys="expert-therapist"/>
    </subjectdef>
    <subjectdef keys="oncologist"/>
    <subjectdef keys="physicist"/>
    <subjectdef keys="radiologist"/>
  </subjectdef>
  <enumerationdef>
    <attributedef name="audience"/>
    <subjectdef keyref="users"/>
  </enumerationdef>
</subjectScheme>

Processors that are aware of the hierarchy that is defined in the subject scheme map will handle filtering and flagging in the following ways:

If "therapist" is excluded, both "novice-therapist" and "expert-therapist" are by default excluded (unless they are explicitly set to be included).
If "therapist" is flagged and "novice-therapist" is not explicitly flagged, processors automatically should flag "novice" since it is a type of therapist.

2.2.2.3.5: Extending subject schemes

The <schemeref> element provides a mechanism for extending a subject scheme. This makes it possible to add new relationships to existing subjects and extend enumerations of controlled values.

The <schemeref> element provides a reference to another subject scheme map. Typically, the referenced subject-scheme map defines a base set of controlled values that are extended by the current subject-scheme map. The values in the referenced subject-scheme map are merged with the values in the current subject-scheme map; the result is equivalent to specifying all of the values in a single subject scheme map.

2.2.2.3.6: Scaling a list of controlled values to define a taxonomy

Optional classification elements make it possible to create a taxonomy from a list of controlled values.

A taxonomy differs from a controlled values list primarily in the degree of precision with which the metadata values are defined. A controlled values list sometimes is regarded as the simplest form of taxonomy. Regardless of whether the goal is a simple list of controlled values or a taxonomy:

The same core elements are used: <subjectScheme> and <subjectdef>.
A category and its subjects can have a binding that enumerates the values of an attribute.

Beyond the core elements and the attribute binding elements, sophisticated taxonomies can take advantage of some optional elements. These optional elements make it possible to specify more precise relationships among subjects. The <hasNarrower>, <hasPart>, <hasKind>, <hasInstance>, and <hasRelated> elements specify the kind of relationship in a hierarchy between a container subject and its contained subjects.

While users who have access to sophisticated processing tools benefit from defining taxonomies with this level of precision, other users can safely ignore this advanced markup and define taxonomies with hierarchies of <subjectdef> elements that are not precise about the kind of relationship between the subjects.

Example: A taxonomy defined using subject scheme elements

The following example defines San Francisco as both an instance of a city and a geographic part of California.

<subjectScheme>
  <hasInstance>
    <subjectdef keys="city" navtitle="City">
      <subjectdef keys="la" navtitle="Los Angeles"/>
      <subjectdef keys="nyc" navtitle="New York City"/>
      <subjectdef keys="sf" navtitle="San Francisco"/>
    </subjectdef>
    <subjectdef keys="state" navtitle="State">
      <subjectdef keys="ca" navtitle="California"/>
      <subjectdef keys="ny" navtitle="New York"/>
    </subjectdef>
  </hasInstance>
  <hasPart>
    <subjectdef keys="place" navtitle="Place">
      <subjectdef keyref="ca">
        <subjectdef keyref="la"/>
        <subjectdef keyref="sf"/>
      </subjectdef>
      <subjectdef keyref="ny">
        <subjectdef keyref="nyc"/>
      </subjectdef>
    </subjectdef>
  </hasPart>
</subjectScheme>

Sophisticated tools can use this subject scheme map to associate content about San Francisco with related content about other California places or with related content about other cities (depending on the interests of the current user).

The subject scheme map also can define relationships between subjects that are not hierarchical. For instance, cities sometimes have "sister city" relationships. An information architect could add a <subjectRelTable> element to define these associative relationships, with a row for each sister-city pair and the two cities in different columns in the row.

2.2.2.3.7: Classification maps

A classification map is a DITA map in which the classification domain has been made available.

The classification domain provides elements that enable map authors to indicate information about the subject matter of DITA topics. The subjects are defined in subjectScheme maps, and the map authors reference the subjects using the @keyref attribute.

2.2.2.3.8: Examples of subject scheme maps

This section contains examples and scenarios that illustrate the use of subject scheme maps.

2.2.2.3.8.1: Example: How hierarchies defined in a subject scheme map affect filtering

This scenario demonstrates how a processor evaluates attribute values when it performs conditional processing for an attribute that is bound to a set of controlled values.

A company defines a subject category for "Operating system", with a key set to "os". There are sub-categories for Linux, Windows, and z/OS, as well as specific Linux variants: Red Hat Linux and SuSE Linux. The company then binds the values that are enumerated in the "Operating system" category to the @platform attribute.

<!-- This examples uses @navtitle rather than <navtitle> solely
to conserve space. Best practises for translate include using <navtitle>. -->
<subjectScheme>
  <subjectdef keys="os" navtitle="Operating system">
    <subjectdef keys="linux" navtitle="Linux">
      <subjectdef keys="redhat" navtitle="RedHat Linux"/>
      <subjectdef keys="suse" navtitle="SuSE Linux"/>
    </subjectdef>
    <subjectdef keys="windows" navtitle="Windows"/>
    <subjectdef keys="zos" navtitle="z/OS"/>
  </subjectdef>
  <enumerationdef>
    <attributedef name="platform"/>
    <subjectdef keyref="os"/>
  </enumerationdef>
</subjectScheme>

The enumeration limits valid values for the @platform attribute to the following: "linux", "redhat", "suse", "windows", and "zos". If any other values are encountered, processors validating against the scheme should issue a warning.

The following table illustrates how filtering and flagging operate when the above map is processed by a processor. The first two columns provide the values specified in the DITAVAL file; the third and fourth columns indicate the results of the filtering or flagging operation

att="platform" val="linux"	att="platform" val="redhat"	How platform="redhat" is evaluated	How platform="linux" is evaluated
action="exclude"	action="exclude"	Excluded.	Excluded.
	action="include" or action="flag"	Excluded. This is an error condition, because if all "linux" content is excluded, "redhat" also is excluded. Applications can recover by generating an error message.	Excluded.
	Unspecified	Excluded, because "redhat" is a kind of "linux", and "linux" is excluded.	Excluded.
action="include"	action="exclude"	Excluded, because all "redhat" content is excluded.	Included.
	action="include"	Included.	Included.
	action="flag"	Included and flagged with the "redhat" flag.	Included.
	Unspecified	Included, because all "linux" content is included.	Included.
action="flag"	action="exclude"	Excluded, because all "redhat" content is excluded.	Included and flagged with the "linux" flag.
	action="include"	Included and flagged with the "linux" flag, because "linux" is flagged and "redhat" is a type of "linux".	Included and flagged with the "linux" flag.
	action="flag"	Included and flagged with the "redhat" flag, because a flag is available that is specifically for "redhat".	Included and flagged with the "linux" flag.
	Unspecified	Included and flagged with the "linux" flag, because "linux" is flagged and "redhat" is a type of linux	Included and flagged with the "linux" flag.
Unspecified	action="exclude"	Excluded, because all "redhat" content is excluded	If the default for @platform values is "include", this is included. If the default for @platform values is "exclude", this is excluded.
	action="include"	Included.	Included, because all "redhat" content is included, and general Linux content also applies to RedHat
	action="flag"	Included and flagged with the "redhat" flag.	Included, because all "redhat" content is included, and general Linux content also applies to RedHat
	Unspecified	If the default for @platform values is "include", this is included. If the default for @platform values is "exclude", this is excluded.	If the default for @platform values is "include", this is included. If the default for @platform values is "exclude", this is excluded.

2.2.2.3.8.2: Example: Extending a subject scheme

You can extend a subject scheme by creating another subject scheme map and referencing the original map using a <schemeref> element. This enables information architects to add new relationships to existing subjects and extend enumerations of controlled values.

A company uses a common subject scheme map (baseOS.ditamap) to set the values for the @platform attribute.

<subjectScheme>
  <subjectdef keys="os" navtitle="Operating system">
    <subjectdef keys="linux" navtitle="Linux">
      <subjectdef keys="redhat" navtitle="RedHat Linux"/>
      <subjectdef keys="suse" navtitle="SuSE Linux"/>
    </subjectdef>
    <subjectdef keys="windows" navtitle="Windows"/>
    <subjectdef keys="zos" navtitle="z/OS"/>
  </subjectdef>
  <enumerationdef>
    <attributedef name="platform"/>
    <subjectdef keyref="os"/>
  </enumerationdef>
</subjectScheme>

The following subject scheme map extends the enumeration defined in baseOS.ditamap. It adds "macos" as a child of the existing "os" subject; it also adds special versions of Windows as children of the existing "windows" subject:

<subjectScheme>
  <schemeref href="baseOS.ditamap"/>
  <subjectdef keyref="os">
    <subjectdef keys="macos" navtitle="Macintosh"/>
    <subjectdef keyref="windows">
      <subjectdef keys="winxp" navtitle="Windows XP"/>
      <subjectdef keys="winvis" navtitle="Windows Vista"/>
    </subjectdef>
  </subjectdef>
</subjectScheme>

Note that the references to the subjects that are defined in baseOS.ditamap use the @keyref attribute. This avoids duplicate definitions of the keys and ensures that the new subjects are added to the base enumeration.

The effective result is the same as the following subject scheme map:

<subjectScheme>
  <subjectdef keys="os" navtitle="Operating system">
    <subjectdef keys="linux" navtitle="Linux">
      <subjectdef keys="redhat" navtitle="RedHat Linux"/>
      <subjectdef keys="suse" navtitle="SuSE Linux"/>
    </subjectdef>
    <subjectdef keys="macos" navtitle="Macintosh"/>
    <subjectdef keys="windows" navtitle="Windows">
      <subjectdef keys="winxp" navtitle="Windows XP"/>
      <subjectdef keys="win98" navtitle="Windows Vista"/>
    </subjectdef>
    <subjectdef keys="zos" navtitle="z/OS"/>
  </subjectdef>
  <enumerationdef>
    <attributedef name="platform"/>
    <subjectdef keyref="os"/>
  </enumerationdef>
</subjectScheme>

2.2.2.3.8.3: Example: Extending a subject scheme upwards

You can broaden the scope of a subject category by creating a new subject scheme map that defines the original subject category as a child of a broader category.

The following subject scheme map creates a "Software" category that includes operating systems as well as applications. The subject scheme map that defines the operation system subjects is pulled in by reference, while the application subjects are defined directly in the subject scheme map below.

<subjectScheme>
  <schemeref href="baseOS.ditamap"/>
  <subjectdef keys="sw" navtitle="Software">
    <subjectdef keyref="os"/>
    <subjectdef keys="app" navtitle="Applications">
      <subjectdef keys="apacheserv" navtitle="Apache Web Server"/>
      <subjectdef keys="mysql" navtitle="MySQL Database"/>
    </subjectdef>
  </subjectdef>
</subjectScheme>

If the subject scheme that is defined in baseOS.ditamap binds the "os" subject to the @platform attribute, the app subjects that are defined in the extension subject scheme do not become part of that enumeration, since they are not part of the "os" subject

To enable the upward extension of an enumeration, information architects can define the controlled values in one subject scheme map and bind the controlled values to the attribute in another subject scheme map. This approach will let information architects bind an attribute to a different set of controlled values with less rework.

An adopter would use the extension subject scheme as the subject scheme that governs the controlled values. Any subject scheme maps that are referenced by the extension subject scheme are effectively part of the extension subject scheme.

2.2.2.3.8.4: Example: Defining values for @deliveryTarget

You can use a subject scheme map to define the values for the @deliveryTarget attribute. This filtering attribute, which is new in DITA 1.3, is intended for use with a set of hierarchical, controlled values.

In this scenario, one department produces electronic publications (EPUB, EPUB2, EPUB3, Kindle, etc.) while another department produces traditional, print-focused output. Each department needs to exclude a certain category of content when they build documentation deliverables.

The following subject scheme map provides a set of values for the @deliveryTarget attribute that accommodates the needs of both departments.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE subjectScheme PUBLIC "-//OASIS//DTD DITA Subject Scheme Map//EN" "subjectScheme.dtd"> 
<subjectScheme>
  <subjectHead>
    <subjectHeadMeta>
      <navtitle>Example of values for the @deliveryTarget attribute</navtitle>
      <shortdesc>Provides a set of values for use with the
        @deliveryTarget conditional-processing attribute. This set of values is
        illustrative only; you can use any values with the @deliveryTarget 
        attribute.</shortdesc>      
    </subjectHeadMeta>
  </subjectHead>
  <subjectdef keys="deliveryTargetValues">
    <topicmeta><navtitle>Values for @deliveryTarget attributes</navtitle></topicmeta>
    <!-- A tree of related values -->
    <subjectdef keys="print">
      <topicmeta><navtitle>Print-primary deliverables</navtitle></topicmeta>
      <subjectdef keys="pdf">
        <topicmeta><navtitle>PDF</navtitle></topicmeta>
      </subjectdef>
      <subjectdef keys="css-print">
        <topicmeta><navtitle>CSS for print</navtitle></topicmeta>
      </subjectdef>
      <subjectdef keys="xsl-fo">
        <topicmeta><navtitle>XSL-FO</navtitle></topicmeta>
      </subjectdef>
      <subjectdef keys="afp">
        <topicmeta><navtitle>Advanced Function Printing</navtitle></topicmeta>
      </subjectdef>
      <subjectdef keys="ms-word">
        <topicmeta><navtitle>Microsoft Word</navtitle></topicmeta>
      </subjectdef>
      <subjectdef keys="indesign">
        <topicmeta><navtitle>Adobe InDesign</navtitle></topicmeta>
      </subjectdef>
      <subjectdef keys="open-office">
        <topicmeta><navtitle>Open Office</navtitle></topicmeta>
      </subjectdef>
    </subjectdef>
    <subjectdef keys="online">
      <topicmeta><navtitle>Online deliverables</navtitle></topicmeta>
      <subjectdef keys="html-based">
        <topicmeta><navtitle>HTML-based deliverables</navtitle></topicmeta>
        <subjectdef keys="html">
          <topicmeta><navtitle>HTML</navtitle></topicmeta>
          <subjectdef keys="html5">
            <topicmeta><navtitle>HTML5</navtitle></topicmeta>
          </subjectdef>
        </subjectdef>
        <subjectdef keys="help">
          <topicmeta><navtitle>Contextual help</navtitle></topicmeta>
          <subjectdef keys="htmlhelp">
            <topicmeta><navtitle>HTML Help</navtitle></topicmeta>
          </subjectdef>
          <subjectdef keys="webhelp">
            <topicmeta><navtitle>Web help</navtitle></topicmeta>
          </subjectdef>
          <subjectdef keys="javahelp">
            <topicmeta><navtitle>Java Help</navtitle></topicmeta>
          </subjectdef>
          <subjectdef keys="eclipseinfocenter">
            <topicmeta><navtitle>Eclipse InfoCenter</navtitle></topicmeta>
          </subjectdef>
        </subjectdef>
        <subjectdef keys="epub">
          <topicmeta><navtitle>EPUB</navtitle></topicmeta>
          <subjectdef keys="epub2">
            <topicmeta><navtitle>EPUB2</navtitle></topicmeta>
          </subjectdef>
          <subjectdef keys="epub3">
            <topicmeta><navtitle>EPUB3</navtitle></topicmeta>
          </subjectdef>
          <subjectdef keys="ibooks">
            <topicmeta><navtitle>iBooks</navtitle></topicmeta>
          </subjectdef>
          <subjectdef keys="nook">
            <topicmeta><navtitle>nook</navtitle></topicmeta>
          </subjectdef>
        </subjectdef>
        <subjectdef keys="kindle">
          <topicmeta><navtitle>Amazon Kindle</navtitle></topicmeta>
          <subjectdef keys="kindle8">
            <topicmeta><navtitle>Kindle Version 8</navtitle></topicmeta>
          </subjectdef>
        </subjectdef>
      </subjectdef>
    </subjectdef>
  </subjectdef>
  <enumerationdef>
    <attributedef name="deliveryTarget"/>
    <subjectdef   keyref="deliveryTargetValues"/>
  </enumerationdef>
</subjectScheme>

2.2.2.4: DITA metadata

Metadata can be applied in both DITA topics and DITA maps. Metadata that is assigned in DITA topics can be supplemented or overridden by metadata that is assigned in a DITA map; this design facilitates the reuse of DITA topics in different DITA maps and use-specific contexts.

2.2.2.4.1: Metadata elements

The metadata elements, many of which map to Dublin core metadata, are available in topics and DITA maps. This design enables authors and information architects to use identical metadata markup in both topics and maps.

The <metadata> element is a wrapper element that contains many of the metadata elements. In topics, the <metadata> element is available in the <prolog> element. In maps, the <metadata> element is available in the <topicmeta> element.

In DITA maps, the metadata elements also are available directly in the <topicmeta> element. Collections of metadata can be shared between DITA maps and topics by using the conref or keyref mechanism.

In general, specifying metadata in a <topicmeta> element is equivalent to specifying it in the <prolog> element of a referenced topic. The value of specifying the metadata at the map level is that the topic then can be reused in other maps where different metadata might apply. Many items in the <topicmeta> element also cascade to nested <topicref> elements within the map.

Note

Not all metadata elements are available in the <metadata> element. However, they are available in either the topic <prolog> element or the map <topicmeta> element.

2.2.2.4.2: Metadata attributes

Certain attributes are common across most DITA elements. These attributes support content referencing, conditional processing, application of metadata, and globalization and localization.

2.2.2.4.2.1: Conditional processing attributes

The metadata attributes specify properties of the content that can be used to determine how the content should be processed. Specialized metadata attributes can be defined to enable specific business-processing needs, such as semantic processing and data mining.

Metadata attributes typically are used for the following purposes:

Filtering content based on the attribute values, for example, to suppress or publish profiled content
Flagging content based on the attribute values, for example, to highlight specific content on output
Performing custom processing, for example, to extract business-critical data and store it in a database

Typically @audience, @platform, @product, @otherprops, @props, @deliveryTarget, and specializations of the @props attributes are used for filtering; the same attributes plus the @rev attribute are used for flagging. The @status and @importance attributes, as well as custom attributes specialized from @base, are used for application-specific behavior, such as identifying metadata to aid in search and retrieval.

Filtering and flagging attributes

The following conditional-processing attributes are available on most elements:

@product: The product that is the subject of the discussion.
@platform: The platform on which the product is deployed.
@audience: The intended audience of the content.
@deliveryTarget: The intended delivery target of the content, for example "html", "pdf", or "epub". This attribute is a replacement for the now deprecated @print attribute.
The @deliveryTarget attribute is specialized from the @props attribute. It is defined in the deliveryTargetAttDomain, which is integrated into all OASIS-provided document-type shells. If this domain is not integrated into a given document-type shell, the @deliveryTarget attribute will not be available.
@rev: The revision or draft number of the current document. (This is used only for flagging.)
@otherprops: Other properties that do not require semantic identification.
@props: A generic conditional processing attribute that can be specialized to create new semantic conditional-processing attributes.

Other metadata attributes

Other attributes are still considered metadata on an element, but they are not designed for filtering or flagging.

@importance

The degree of priority of the content. This attribute takes a single value from an enumeration.

@status

The current state of the content. This attribute takes a single value from an enumeration.

@base

A generic attribute that has no specific purpose, but is intended to act as the basis for specialized attributes that have a simple value syntax like the conditional processing attributes (one or more alphanumeric values separated by whitespace or parenthesized groups of values).

@outputclass

Provides a label on one or more element instances, typically to specify a role or other semantic distinction. As the @outputclass attribute does not provide a formal type declaration or the structural consistency of specialization, it should be used sparingly, usually only as a temporary measure while a specialization is developed. For example, <uicontrol> elements that define button labels could be distinguished by adding an @outputclass attribute:

<uicontrol outputclass="button">Cancel</uicontrol>

The value of the @outputclass attribute can be used to trigger XSLT or CSS rules, while providing a mapping to be used for future migration to a more specialized set of user interface elements.

2.2.2.4.2.2: Translation and localization attributes

DITA elements have several attributes that support localization and translation.

@xml:lang: Identifies the language of the content, using the standard language and country codes. For instance, French Canadian is identified by the value fr-CA. The @xml:lang attribute asserts that all content and attribute values within the element bearing the attribute are in the specified language, except for contained elements that declare a different language.
@translate: Determines whether the element requires translation. A default value can often be inferred from the element type. For example, <apiname> might be untranslated by default, whereas <p> might be translated by default.
@dir: Determines the direction in which the content should be rendered.

2.2.2.4.2.3: Architectural attributes

The architectural attributes specify the version of DITA that the content supports; they also identify the DITA domains, structural types, and specializations that are in use by the content.

The architectural attributes should not be marked up in the source DITA map and topics. Instead, the values of the architectural attributes are handled by the processor when the content is processed, preferably through defaults set in the XML grammar. This practice ensures that the DITA content instances do not specify invalid values for the architectural attributes.

The architectural attributes are as follows:

@class: This attribute identifies the specialization hierarchy for the element type. Every DITA element (except the <dita> element that is used as the root of a ditabase document) MUST declare a @class attribute.
@domains: This attribute identifies the domain modules (and optionally the structural modules) that are used in a map or topic. Each module also declares its module dependencies. The root element of every topic and map MUST declare a @domains attribute.
@DITAArchVersion: This attribute identifies the version of the DITA architecture that is used by the XML grammar. The root element of every topic and map MUST declare a @DITAArchVersion attribute. The attribute is declared in a DITA namespace to allow namespace-sensitive tools to detect DITA markup.

To make the document instance usable in the absence of an XML grammar, a normalization process can set the architectural attributes in the document instance.

2.2.2.4.3: Metadata in maps and topics

Topic metadata can be specified in a DITA map as well as in the topics that the map references. By default, metadata in the map supplements or overrides metadata that is specified at the topic level, unless the @lockmeta attribute of the <topicmeta> element is set to "no".

Where metadata about topics can be specified

Information about topics can be specified as metadata on the map, as attributes on the <topicref> element, or as metadata attributes or elements in the topic itself:

DITA map: Metadata elements

At the map level, properties can be set by using metadata elements. They can be set for an individual topic, for a set of topics, or globally for the entire document. The metadata elements are authored within a <topicmeta> element, which associates metadata with the parent element and its children. Because the topics in a branch of the hierarchy typically have some common subjects or properties, this is a convenient mechanism to define properties for a set of topics. For example, the <topicmeta> element in a <relcolspec> can associate metadata with all the topics that are referenced in the <reltable> column.

A map can override or supplement everything about a topic except its primary title and body content. All the metadata elements that are available in a topic also are available in a map. In addition, a map can provide alternate titles and a short description. The alternate titles can override their equivalent titles in the topic. The short description in the map MAY override the short description in the topic if the <topicref> element specifies a @copy-to attribute.

DITA map: Attributes of the <topicref> element

At the map level, properties can be set as attributes of the <topicref> element.

DITA topic

Within a topic, authors can either set metadata attributes on the root element or add metadata elements in the <prolog> element.

How metadata set at both the map and topic level intersects

In a topic, the metadata elements apply to the entire topic. In a map, they supplement or override any metadata that is provided in the referenced topics. When the same metadata element or attribute is specified in both a map and a topic, by default the value in the map takes precedence; the assumption here is that the author of the map has more knowledge of the reusing context than the author of the topic. The @lockmeta attribute on the <topicmeta> element controls whether map-specified values override values in the referenced topic.

The <navtitle> element is an exception to the rule of how metadata specified by the <topicmeta> element cascades. The content of the <navtitle> element is used as a navigation title only if the @locktitle attribute of the parent <topicref> element is set to "yes".

2.2.2.4.4: Cascading of metadata attributes in a DITA map

Certain map-level attributes cascade throughout a map, which facilitates attribute and metadata management. When attributes cascade, they apply to the elements that are children of the element where the attributes were specified. Cascading applies to a containment hierarchy, as opposed to a element-type hierarchy.

The following attributes cascade when set on the <map> element or when set within a map:

@audience, @platform, @product, @otherprops, @rev
@props and any attribute specialized from @props
@linking, @toc, @print, @search
@format, @scope, @type
@xml:lang, @dir, @translate
@processing-role
@cascade

Cascading is additive for attributes that accept multiple values, except when the @cascade attribute is set to avoid adding values to attributes. For attributes that take a single value, the closest value defined on a containing element takes effect. In a relationship table, row-level metadata is considered more specific than column-level metadata, as shown in the following containment hierarchy:

<map> (most general)
- <topicref> container (more specific)
  - <topicref> (most specific)
- <reltable> (more specific)
  - <relcolspec> (more specific)
    - <relrow> (more specific)
      - <topicref> (most specific)

Merging of cascading attributes

The @cascade attribute can be used to modify the additive nature of attribute cascading (though it does not turn off cascading altogether). The attribute has two predefined values: "merge" and "nomerge".

cascade="merge": The metadata attributes cascade; the values of the metadata attributes are additive. This is the processing default for the @cascade attribute and was the only defined behavior for DITA 1.2 and earlier.
cascade="nomerge": The metadata attributes cascade; however, they are not additive for <topicref> elements that specify a different value for a specific metadata attribute. If the cascading value for an attribute is already merged based on multiple ancestor elements, that merged value continues to cascade until a new value is encountered (that is, setting cascade="nomerge" does not undo merging that took place on ancestors).

Implementers MAY define their own custom, implementation-specific tokens. To avoid name conflicts between implementations or with future additions to the standard, implementation-specific tokens SHOULD consist of a prefix that gives the name or an abbreviation for the implementation followed by a colon followed by the token or method name.

For example, a processor might define the token "appToken:audience" in order to specify cascading and merging behaviors for only the @audience attribute. The following rules apply:

The predefined values for the @cascade attribute MUST precede any implementation-specific tokens, for example, cascade="merge appToken:audience".
Tokens can apply to a set of attributes, specified as part of the @cascade value. In that case, the syntax for specifying those values consists of the implementation-specific token, followed by a parenthetical group that uses the same syntax as groups within the @audience, @platform, @product, and @otherprops attributes. For example, a token that applies to only @platform and @product could be specified as cascade="appname:token(platform product)".

Examples of the @cascade attribute in use

Consider the following code examples:

Map A

<map audience="a b" cascade="merge">
     <topicref href="topic.dita" audience="c"/>
</map>

Map B

<map audience="a b" cascade="nomerge">
     <topicref href="topic.dita" audience="c"/>
</map>

For map A, the values for the attribute are merged, and the effective value of the @audience attribute for topic.dita is "a b c". For map B, the values for the attribute are not additive, and the effective value of the @audience attribute for topic.dita is "c".

In the following example, merging is active at the map level but turned off below:

Map C

<map platform="a" product="x" cascade="merge">
  <topicref href="one.dita" platform="b" product="y">
    <topicref href="two.dita" cascade="nomerge" product="z"/>
  </topicref>
</map>

In map C, the reference to one.dita has effective merged values of "a b" for @platform and "x y" for @product.

The reference to two.dita turns off merging, so the explicit @product value of "z" is used (it does not merge with ancestor values). The @platform attribute is not present, so the already-merged value of "a b" continues to cascade and is the effective value of @platform on this reference.

Order for processing cascading attributes in a map

When determining the value of an attribute, processors MUST evaluate each attribute on each individual element in a specific order; this order is specified in the following list. Applications MUST continue through the list until a value is established or until the end of the list is reached (at which point no value is established for the attribute). In essence, the list provides instructions on how processors can construct a map where all attribute values are set and all cascading is complete.

For example, in the case of <topicref toc="yes">, applications MUST stop at item 2 in the list; a value is specified for @toc in the document instance, so @toc values from containing elements will not cascade to that specific <topicref> element. The toc="yes" setting on that <topicref> element will cascade to contained elements, provided those elements reach item 5 below when evaluating the @toc attribute.

For attributes within a map, the following processing order MUST occur:

The @conref and @keyref attributes are evaluated.

The explicit values specified in the document instance are evaluated. For example, a <topicref> element with the @toc attribute set to "no" will use that value.
The default or fixed attribute values are evaluated. For example, the @toc attribute on the <reltable> element has a default value of "no".

The default values that are supplied by a controlled values file are evaluated.

The attributes cascade.
The processing-supplied default values are applied.
After the attributes are resolved within the map, they cascade to referenced maps.

Note

The processing-supplied default values do not cascade to other maps. For example, most processors will supply a default value of toc="yes" when no @toc attribute is specified. However, a processor-supplied default of toc="yes" MUST not override a value of toc="no" that is set on a referenced map. If the toc="yes" value is explicitly specified, is given as a default through a DTD, XSD, RNG, or controlled values file, or cascades from a containing element in the map, it MUST override a toc="no" setting on the referenced map. See Map-to-map cascading behaviors for more details.
Repeat steps 1 to 4 for each referenced map.
The attributes cascade within each referenced map.
The processing-supplied default values are applied within each referenced map.
Repeat the process for maps referenced within the referenced maps.

2.2.2.4.5: Reconciling topic and map metadata elements

The <topicmeta> element in maps contains numerous elements that can be used to declare metadata. These metadata elements have an effect on the parent <topicref> element, any child <topicref> elements, and – if a direct child of the <map> element – on the map as a whole.

For each element that can be contained in the <topicmeta> element, the following table addresses the following questions:

How does it apply to the topic?: This column describes how the metadata specified within the <topicmeta> element interacts with the metadata specified in the topic. In most cases, the properties are additive. For example, when the <audience> element is set to "user" at the map level, the value "user" is added during processing to any audience metadata that is specified within the topic.
Does it cascade to other topics in the map?: This column indicates whether the specified metadata value cascades to nested <topicref> elements. For example, when an <audience> element is set to "user" at the map level, all child <topicref> elements implicitly have an <audience> element set to "user" also. Elements that can apply only to the specific <topicref> element, such as <linktext>, do not cascade.
What is the purpose when specified on the <map> element?: The map element allows metadata to be specified for the entire map. This column describes what effect, if any, an element has when specified at this level.

Topicmeta elements and their properties

Element	How does it apply to the topic?	Does it cascade to child <topicref> elements?	What is the purpose when set on the <map> element?
<audience>	Add to the topic	Yes	Specify an audience for the entire map
<author>	Add to the topic	Yes	Specify an author for the entire map
<category>	Add to the topic	Yes	Specify a category for the entire map
<copyright>	Add to the topic	Yes	Specify a copyright for the entire map
<critdates>	Add to the topic	Yes	Specify critical dates for the entire map
<data>	Add to the topic	No, unless specialized for a purpose that cascades	No stated purpose, until the element is specialized
<data-about>	Add the property to the specified target	No, unless specialized for a purpose that cascades	No stated purpose, until the element is specified
<foreign>	Add to the topic	No, unless specialized for a purpose that cascades	No stated purpose, until the element is specified
<keywords>	Add to the topic	No	No stated purpose
<linktext>	Not added to the topic; applies only to links created based on this occurrence in the map	No	No stated purpose
<metadata>	Add to the topic	Yes	Specify metadata for the entire map
<navtitle>	Not added to the topic; applies only to navigation that is created based on this occurrence in the map. The navigation title will be used whenever the @locktitle attribute on the containing <topicref> element is set to "yes".	No	No stated purpose
<othermeta>	Add to the topic	No	Define metadata for the entire map
<permissions>	Add to the topic	Yes	Specify permissions for the entire map
<prodinfo>	Add to the topic	Yes	Specify product info for the entire map
<publisher>	Add to the topic	Yes	Specify a publisher for the map
<resourceid>	Add to the topic	No	Specify a resource ID for the map
<searchtitle>	Replace the one in the topic. If multiple <searchtitle> elements are specified for a single target, processors can choose to issue a warning.	No	No stated purpose
<shortdesc>	Only added to the topic when the <topicref> element specifies a @copy-to attribute. Otherwise, it applies only to links created based on this occurrence in the map. Note Processors MAY or MAY NOT implement this behavior.	No	Provide a description of the map
<source>	Add to the topic	No	Specify a source for the map
<unknown>	Add to the topic	No, unless specialized for a purpose that cascades	No stated purpose, until the element is specified
<ux-window>	Not added to the topic	No	Definitions are global, so setting at map level is equivalent to setting anywhere else.

Example of metadata elements cascading in a DITA map

The following code sample illustrates how an information architect can apply certain metadata to all the DITA topics in a map:

<map title="DITA maps" xml:lang="en-us">
	<topicmeta>
		<author>Kristen James Eberlein</author>
		<copyright>
			<copyryear year="2009"/>
			<copyrholder>OASIS</copyrholder>
		</copyright>
	</topicmeta>
	<topicref href="dita_maps.dita" navtitle="DITA maps">
		<topicref href="definition_ditamaps.dita" navtitle="Definition of DITA maps"></topicref>
		<topicref href="purpose_ditamaps.dita" navtitle="Purpose of DITA maps"></topicref>
		<!-- ... -->
       </topicref>
</map>

The author and copyright information cascades to each of the DITA topics referenced in the DITA map. When the DITA map is processed to XHTML, for example, each XHTML file contains the metadata information.

2.2.2.4.6: Map-to-map cascading behaviors

When a DITA map (or branch of a DITA map) is referenced by another DITA map, by default, certain rules apply. These rules pertain to the cascading behaviors of attributes, metadata elements, and roles assigned to content (for example, the role of "Chapter" assigned by a <chapter> element). Attributes and elements that cascade within a map generally follow the same rules when cascading from one map to another map, but there are some exceptions and additional rules that apply.

2.2.2.4.6.1: Cascading of attributes from map to map

Certain elements cascade from map to map, although some of the attributes that cascade within a map do not cascade from map to map.

The following attributes cascade from map to map:

@audience, @platform, @product, @otherprops, @rev
@props and any attribute specialized from @props
@linking, @toc, @print, @search
@type
@translate
@processing-role
@cascade

Note that the above list excludes the following attributes:

@format: The @format attribute must be set to "ditamap" in order to reference a map or a branch of a map, so it cannot cascade through to the referenced map.
@xml:lang and @dir: Cascading behavior for @xml:lang is defined in The @xml:lang attribute. The @dir attribute work the same way.
@scope: The value of the @scope attribute describes the map itself, rather than the content. When the @scope attribute is set to "external", it indicates that the referenced map itself is external and unavailable, so the value cannot cascade into that referenced map.

The @class attribute is used to determine the processing roles that cascade from map to map. See Cascading of roles from map to map for more information.

As with values that cascade within a map, the cascading is additive if the attribute permits multiple values (such as @audience). When the attribute only permits one value, the cascading value overrides the top-level element.

Example of attributes cascading between maps

For example, assume the following references in test.ditamap:

<map>
  <topicref href="a.ditamap" format="ditamap" toc="no"/>
  <mapref   href="b.ditamap" audience="developer"/>
  <topicref href="c.ditamap#branch1" format="ditamap" print="no"/>
  <mapref   href="c.ditamap#branch2" platform="myPlatform"/>
</map>

The map a.ditamap is treated as if toc="no" is specified on the root <map> element. This means that the topics that are referenced by a.ditamap do not appear in the navigation generated by test.ditamap (except for branches within the map that explicitly set toc="yes").
The map b.ditamap is treated as if audience="developer" is set on the root <map> element. If the @audience attribute is already set on the root <map> element within b.ditamap, the value "developer" is added to any existing values.
The element with id="branch1" within the map c.ditamap is treated as if print="no" is specified on that element. This means that the topics within the branch with id="branch1" do not appear in the printed output generated by test.ditamap (except for nested branches within that branch that explicitly set print="yes").
The element with id="branch2" within the map c.ditamap is treated as if platform="myPlatform" is specified on that element. If the @platform attribute is already specified on the element with id="branch", the value "myPlatform" is added to existing values.

2.2.2.4.6.2: Cascading of metadata elements from map to map

Elements that are contained within <topicmeta> or <metadata> elements follow the same rules for cascading from map to map as the rules that apply within a single DITA map.

For a complete list of which elements cascade within a map, see the column "Does it cascade to child <topicref> elements? " in the topic Reconciling topic and map metadata elements .

Note

It is possible that a specialization might define metadata that should replace rather than add to metadata in the referenced map, but DITA (by default) does not currently support this behavior.

For example, consider the following code examples:

`test-2.ditamap`

<map>
    <topicref href="a.ditamap" format="ditamap">
        <topicmeta>
            <shortdesc>This map contains information about Acme defects.</shortdesc>
        </topicmeta>
    </topicref>
    <topicref href="b.ditamap" format="ditamap">
        <topicmeta>
            <audience type="programmer"/>
        </topicmeta>
    </topicref>    
    <mapref href="c.ditamap" format="ditamap"/>
    <mapref href="d.ditamap" format="ditamap"/>
    </map>

`b.ditamap`

<map>
    <topicmeta>
        <audience type="writer"/>
    </topicmeta>
    <topicref href="b-1.dita"/>
    <topicref href="b-2.dita"/>
</map>

When test-2.ditamap is processed, the following behavior occurs:

Because the <shortdesc> element does not cascade, it does not apply to the DITA topics that are referenced in a.ditamap.
Because the <audience> element cascades, the <audience> element in the reference to b.ditamap combines with the <audience> element that is specified at the top level of b.ditamap. The result is that the b-1.dita topic and b-2.dita topic are processed as though hey each contained the following child <topicmeta> element:
```
<topicmeta>
    <audience type="programmer"/>
    <audience type="writer"/>
</topicmeta>
```

2.2.2.4.6.3: Cascading of roles from map to map

When specialized <topicref> elements (such as <chapter> or <mapref>) reference a map, they typically imply a semantic role for the referenced content.

The semantic role reflects the @class hierarchy of the referencing <topicref> element; it is equivalent to having the @class attribute from the referencing <topicref> cascade to the top-level <topicref> elements in the referenced map. Although this cascade behavior is not universal, there are general guidelines for when @class values should be replaced.

When a <topicref> element or a specialization of a <topicref> element references a DITA resource, it defines a role for that resource. In some cases this role is straightforward, such as when a <topicref> element references a DITA topic (giving it the already known role of "topic"), or when a <mapref> element references a DITA map (giving it the role of "DITA map").

Unless otherwise instructed, a specialized <topicref> element that references a map supplies a role for the referenced content. This means that, in effect, the @class attribute of the referencing element cascades to top-level topicref elements in the referenced map. In situations where this should not happen - such as all elements from the mapgroup domain - the non-default behavior should be clearly specified.

For example, when a <chapter> element from the bookmap specialization references a map, it supplies a role of "chapter" for each top-level <topicref> element in the referenced map. When the <chapter> element references a branch in another map, it supplies a role of "chapter" for that branch. The @class attribute for <chapter> ("- map/topicref bookmap/chapter ") cascades to the top-level <topicref> element in the nested map, although it does not cascade any further.

Alternatively, the <mapref> element in the mapgroup domain is a convenience element; the top-level <topicref> elements in the map referenced by a <mapref> element MUST NOT be processed as if they are <mapref> elements. The @class attribute from the <mapref> element ("+ map/topicref mapgroup-d/mapref ") does not cascade to the referenced map.

In some cases, preserving the role of the referencing element might result in out-of-context content. For example, a <chapter> element that references a bookmap might pull in <part> elements that contain nested <chapter> elements. Treating the <part> element as a <chapter> will result in a chapter that nests other chapters, which is not valid in bookmap and might not be understandable by processors. The result is implementation specific; processors MAY choose to treat this as an error, issue a warning, or simply assign new roles to the problematic elements.

Example of cascading roles between maps

Consider the scenario of a <chapter> element that references a DITA map. This scenario could take several forms:

Referenced map contains a single top-level <topicref> element: The entire branch functions as if it were included in the bookmap; the top-level <topicref> element is processed as if it were the <chapter> element.
Referenced map contains multiple top-level <topicref> elements: Each top-level <topicref> element is processed as if it were a <chapter> element (the referencing element).
Referenced map contains a single <appendix> element: The <appendix> element is processed as it were a <chapter> element.
Referenced map contains a single <part> element, with nested <chapter> elements.: The <part> element is processed as it were a chapter element. Nested <chapter> elements might not be understandable by processors; applications MAY recover as described above.
<chapter> element references a single <topicref> element rather than a map: The referenced <topicref> element is processed as if it were a <chapter> element.

2.2.2.4.7: Context hooks and window metadata for user assistance

Context hook information specified in the <resourceid> element in the DITA map or in a DITA topic enables processors to generate the header, map, alias and other types of support files that are required to integrate the user assistance with the application. Some user assistance topics might need to be displayed in a specific window or viewport, and this windowing metadata can be defined in the DITA map within the <ux-window> element.

Context hook and windowing information is ignored if the processor does not support this metadata.

User interfaces for software application often are linked to user assistance (such as help systems and tool tips) through context hooks. Context hooks are identifiers that associate a part of the user interface with the location of a help topic. Context hooks can be direct links to URIs, but more often they are indirect links (numeric context identifiers and context strings) that can processed into external resource files. These external resource and mapping files are then used directly by context-sensitive help systems and other downstream applications.

Context hooks can define either one-to-one or one-to-many relationships between user interface controls and target help content.

The metadata that is available in <resourceid> and <ux-window> provides flexibility for content developers:

You can overload maps and topics with all the metadata needed to support multiple target help systems. This supports single-sourcing of help content and help metadata.
You can choose whether to add <resourceid> metadata to <topicref> elements, <prolog> elements, or both. Context-dependent metadata might be best be kept with maps, while persistent, context-independent metadata might best stay with topics in <prolog> elements

Context hook information is defined within DITA topics and DITA maps through attributes of the <resourceid> element.

In some help systems, a topic might need to be displayed in a specifically sized or featured window. For example, a help topic might need to be displayed immediately adjacent to the user interface control that it supports in a window of a specific size that always remains on top, regardless of the focus within the operating system. Windowing metadata can be defined in the DITA map within the <ux-window> element.

The <ux-window> element provides the @top, @left, @height, @width, @on-top, @features, @relative, and @full-screen attributes.

2.2.3: 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.

2.2.3.1: ID attribute

The @id attribute assigns an identifier to DITA elements so that the elements can be referenced.

The @id attribute is available for most elements. An element must have a valid value for the @id attribute before it can be referenced using a fragment identifier. The requirements for the @id attribute differ depending on whether it is used on a topic element, a map element, or an element within a topic or map.

All values for the @id attribute must be XML name tokens.

The @id attributes for topic and map elements are declared as XML attribute type ID; therefore, they must be unique with respect to other XML IDs within the XML document that contains the topic or map element. The @id attribute for most other elements within topics and maps are not declared to be XML IDs; this means that XML parsers do not require that the values of those attributes be unique. However, the DITA specification requires that all IDs be unique within the context of a topic. For this reason, tools might provide an additional layer of validation to flag violations of this rule.

Within documents that contain multiple topics, the values of the @id attribute for all non-topic elements that have the same nearest-ancestor-topic element should be unique with respect to each other. The values of the @id attribute for non-topic elements can be the same as non-topic elements with different nearest-ancestor-topic elements. Therefore, within a single DITA document that contains more than one topic, the values of the @id attribute of the non-topic elements need only to be unique within each topic.

Within a map document, the values of the @id attributes for all elements SHOULD be unique. When two elements within a map have the same value for the @id attribute, processors MUST resolve references to that ID to the first element with the given ID value in document order.

Summary of requirements for the @id attribute

Element	XML attribute type for @id	Must be unique within	Required?
<map>	ID	document	No
<topic>	ID	document	Yes
sub-map (elements nested within a map)	NMTOKEN	document	Usually no, with some exceptions
sub-topic (elements nested within a topic)	NMTOKEN	individual topic	Usually no, with some exceptions

Note

For all elements other than footnote (<fn>), the presence of a value for the @id attribute has no impact on processing. For <fn>, the presence or absence of a valid @id attribute affects how the element is processed. This is important for tools that automatically assign @id attributes to all elements.

2.2.3.2: DITA linking

DITA supports many different linking elements, but they all use the same set of attributes to describe relationships between content.

URI-based addressing

URI-based links are described by the following attributes.

@href: The @href attribute specifies the URI of the resource that is being addressed.
@format: The @format attribute identifies the format of the resource being addressed. For example, references to DITA topics are identified with format="dita", whereas references to DITA maps use format="ditamap". References to other types of content should use other values for this attribute. By default, references to non-XML content use the extension of the URI in the @href attribute as the effective format.
@scope: The @scope attribute describes the closeness of the relationship between the current document and the target resource. Resources in the same information unit are considered "local"; resources in the same system as the referencing content but not part of the same information unit are considered "peer"; and resources outside the system, such as Web pages, are considered "external".
@type: The @type attribute is used on cross-references to describe the target of the reference. Most commonly, the @type attribute names the element type being referenced when format="dita".

These four attributes act as a unit, describing whatever link is established by the element that carries them.

The @format and @scope attributes are assigned default values based on the URI that is specified in the @href attribute. Thus they rarely need to be explicitly specified in most cases. However, they can be useful in many non-traditional linking scenarios or environments.

Indirect key-based addressing

DITA also supports indirect links and cross-references in which a DITA map assigns unique names, or keys, to the resources being referenced by the publication. This is done using <topicref> elements that specify the @keys attribute. Using the @keyref attribute, individual links, cross-references, and images then reference resources by their keys instead of their URIs . Links defined using @keyref thus allow context-specific linking behavior. That is, the links in a topic or map might resolve to one set of resources in one context, and a completely different set of resources in another, without the need for any modifications to the link markup.

When links are defined using @keyref, values for the four linking attributes described above are typically all specified (or given default values) on the key defining element.

2.2.3.3: 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.

URI references address resources and (in some cases) subcomponents of those resources. In this context, a resource is a DITA document (map, topic, or DITA base document) or a non-DITA resource (for example, an image, a Web page, or a PDF document).

URI references that are URLs must conform to the rules for URLs and URIs. Windows paths that contain a backslash (\) are not valid URLs.

URIs and fragment identifiers

For DITA resources, fragment identifiers can be used with the URI to address individual elements. The fragment identifier is the part of the URI that starts with a number sign (#), for example, #topicid/elementid. URI references also can include a query component that is introduced with a question mark (?). DITA processors MAY ignore queries on URI references to DITA resources. URI references that address components in the same document MAY consist of just the fragment identifier.

For addressing DITA elements within maps and topics or individual topics within documents containing multiple topics, URI references must include the appropriate DITA-defined fragment identifier. URI references can be relative or absolute. A relative URI reference can consist of just a fragment identifier. Such a reference is a reference to the document that contains the reference.

Addressing non-DITA targets using a URI

DITA can use URI references to directly address non-DITA resources. Any fragment identifier used must conform to the fragment identifier requirements that are defined for the target media type or provided by processors.

Addressing elements within maps using a URI

When addressing elements within maps, URI references can include a fragment identifier that includes the ID of the map element, for example, filename.ditamap#mapId or #mapId. The same-topic, URI-reference fragment identifier of a period (.) can not be used in URI references to elements within maps.

Addressing topics using a URI

When addressing a DITA topic element, URI references can include a fragment identifier that includes the ID of the topic element (filename.dita#topicId or #topicId). When addressing the DITA topic element that contains the URI reference, the URI reference might include the same topic fragment identifier of "." (#.).

Topics always can be addressed by a URI reference whose fragment identifier consists of the topic ID. For the purposes of linking, a reference to a topic-containing document addresses the first topic within that document in document order. For the purposes of rendering, a reference to a topic-containing document addresses the root element of the document.

Consider the following examples:

Given a document whose root element is a topic, a URI reference (with no fragment identifier) that addresses that document implicitly references the topic element.
Given a <dita> document that contains multiple topics, for the purposes of linking, a URI reference that addresses the <dita> document implicitly references the first child topic.
Given a <dita> document that contains multiple topics, for the purposes of rendering, a URI reference that addresses the <dita> document implicitly references all the topics that are contained by the <dita> element. This means that all the topics that are contained by the<dita> element are rendered in the result.

Addressing non-topic elements using a URI

When addressing a non-topic element within a DITA topic, a URI reference must use a fragment identifier that contains the ID of the ancestor topic element of the non-topic element being referenced, a slash ("/"), and the ID of the non-topic element (filename.dita#topicId/elementId or #topicId/elementId). When addressing a non-topic element within the topic that contains the URI reference, the URI reference can use an abbreviated fragment-identifier syntax that replaces the topic ID with "." (#./elementId).

This addressing model makes it possible to reliably address elements that have values for the @id attribute that are unique within a single DITA topic, but which might not be unique within a larger XML document that contains multiple DITA topics.

Examples: URI reference syntax

The following table shows the URI syntax for common use cases.

Use case	Sample syntax
Reference a table in a topic at a network location	`"http://example.com/file.dita#topicID/tableID"`
Reference a section in a topic on a local file system	`"directory/file.dita#topicID/sectionID"`
Reference a figure contained in the same XML document	`"#topicID/figureID"`
Reference a figure contained in the same topic of an XML document	`"#./figureID"`
Reference an element within a map	`"http://example.com/map.ditamap#elementID"` (and a value of "ditamap" for the @format attribute)
Reference a map element within the same map document	`"#elementID"` (and a value of "ditamap" for the @format attribute)
Reference an external Web site	`"http://www.example.com"`, `"http://www.example.com#somefragment"` or any other valid URI
Reference an element within a local map	`"filename.ditamap#elementid"` (and a value of "ditamap" for the @format attribute)
Reference a local map	`"filename.ditamap"` (and a value of "ditamap" for the @format attribute)
Reference a local topic	Reference a local topic `"filename.dita"` or "`path/filename.dita"`
Reference a specific topic in a local document	`"filename.dita#topicid"` or `"path/filename.dita#topicid"`
Reference a specific topic in the same file	`"#topicid"`
Reference the same topic in the same XML document	`"#."`
Reference a peer map for cross-deliverable linking	`"../book-b/book-b.ditamap"` (and a value of "ditamap" for the @format attribute, a value of "peer" for the @scope attribute, and a value for the @keyscope attribute)

2.2.3.4: 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.

For information about using keys to define and reference controlled values, see Subject scheme maps and their usage.

Note

The material in this section of the DITA specification is exceptionally complex; it is targeted at implementers who build processors and other rendering applications.

2.2.3.4.1: Core concepts for working with keys

The concepts described below are critical for a full understanding of keys and key processing.

The use of the phases "<map> element" or "<topicref> element" should be interpreted as "<map> element and any specialization of <map> element " or " <topicref> element or any specialization of <topicref> element."

Definitions related to 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.

Key definitions

A key definition binds one or more keys to zero or more resources. Resources can be:

Any URI-addressed resource that is referenced directly by the @href attribute or indirectly by the @keyref attribute on the key definition. References to the key are considered references to the URI-addressed resource.
(If the key definition contains a child <topicmeta> element) The child elements of the <topicmeta> element. The content of those elements can be used to populate the content of elements that reference the key.

If a key definition does not contain a <topicmeta> element and does not refer to a resource by @href or @keyref, it is nonetheless a valid key definition. References to the key definition are considered resolvable, but no linking or content transclusion occurs.

Key scopes

All key definitions and key references exist within a key scope. If the @keyscope attribute is never specified within the map hierarchy, all keys exist within a single, default key scope.

Additional key scopes are created when the @keyscope attribute is used. The @keyscope attribute specifies a name or names for the scope. Within a map hierarchy, key scopes are bounded by the following:

The root map.
The root element of submaps when the root elements of the submaps specify the @keyscope attribute
Any <topicref> elements that specify the @keyscope attribute

Key spaces

The key space associated with a key scope is used to resolve all key references that occur immediately within that scope. Key references in child scopes are resolved using the key spaces that are associated with those child scopes.

A key scope is associated with exactly one key space. That key space contains all key definitions that are located directly within the scope; it might also contain definitions that exist in other scopes. Specifically, the key space associated with a key scope is comprised of the following key definitions, in order of precedence:

All key definitions from the key space associated with the parent key scope, if any.
Key definitions within the scope-defining element, including those defined in directly-addressed, locally-scoped submaps, but excluding those defined in child scopes. (Keys defined in child scopes cannot be addressed without qualifiers.)
The key definitions from child scopes, with each key prepended by the child scope name followed by a period. If a child scope has multiple names, the keys in that scope are addressable from the parent scope using any of the scope names as a prefix.

Note

Because of rules 1 and 3, the key space that is associated with a child scope includes the scope-qualified copies of its own keys that are inherited from the key space of the parent scope, as well as those from other "sibling" scopes.

Effective key definitions

A key space can contain many definitions for a given key, but only one definition is effective for the purpose of resolving key references.

When a key has a definition in the key space that is inherited from a parent scope, that definition is effective. Otherwise, a key definition is effective if it is first in a breadth-first traversal of the locally-scoped submaps beneath the scope-defining element. Put another way, a key definition is effective if it is the first definition for that key name in the shallowest map that contains that key definition. This allows higher-level map authors to override keys defined in referenced submaps.

Note

A key definition that specifies more than one key name in its @keys attribute might be the effective definition for some of its keys but not for others.

Within a key scope, keys do not have to be defined before they are referenced. The key space is effective for the entire scope, so the order of key definitions and key references relative to one another is not significant. This has the following implications for processors:

All key spaces for a root map must be determined before any key reference processing can be performed.
Maps referenced solely by key reference have no bearing on key space contents.

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. See Example: How key scopes affect key precedence for more information.

2.2.3.4.2: Key scopes

Key scopes enable map authors to specify different sets of key definitions for different map branches.

A key scope is defined by a <map> or <topicref> element that specifies the @keyscope attribute. The @keyscope attribute specifies the names of the scope, separated by spaces.

A key scope includes the following components:

The scope-defining element
The elements that are contained by the scope-defining element, minus the elements that are contained by child key scopes
The elements that are referenced by the scope-defining element or its descendants, minus the elements that are contained by child key scopes

If the @keyscope attribute is specified on both a reference to a DITA map and the root element of the referenced map, only one scope is created; the submap does not create another level of scope hierarchy. The single key scope that results from this scenario has multiple names; its names are the union of the values of the @keyscope attribute on the map reference and the root element of the submap. This means that processors can resolve references to both the key scopes specified on the map reference and the key scopes specified on the root element of the submap.

The root element of a root map always defines a key scope, regardless of whether a @keyscope attribute is present. All key definitions and key references exist within a key scope, even if it is an unnamed, implicit key scope that is defined by the root element in the root map.

Each key scope has its own key space that is used to resolve the key references that occur within the scope. The key space that is associated with a key scope includes all of the key definitions within the key scope. This means that different key scopes can have different effective key definitions:

A given key can be defined in one scope, but not another.
A given key also can be defined differently in different key scopes.

Key references in each key scope are resolved using the effective key definition that is specified within its own key scope.

Example: Key scopes specified on both the map reference and the root element of the submap

Consider the following scenario:

Root map

<map>
  <mapref keyscope="A" href="installation.ditamap"/>
  <!-- ... -->
</map>

`installation.ditamap`

<map keyscope="B">
  <!-- ... -->
</map>

Only one key scope is created; it has key scope names of "A" and "B".

2.2.3.4.3: 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.

Syntax

For references to topics, maps, and non-DITA resources, the value of the @keyref attribute is simply a key name (for example, keyref="topic-key").

For references to non-topic elements within topics, the value of the @keyref attribute is a key name, a slash ("/"), and the ID of the target element (for example, keyref="topic-key/some-element-id".)

Example

For example, consider this topic in the document file.dita:

<topic id="topicid">
 <title>Example referenced topic</title>
 <body>
  <section id="section-01">Some content.</section>
 </body>
</topic>

and this key definition:

<map>
  <topicref keys="myexample"
    href="file.dita"
  />
</map>

A cross reference of the form keyref="myexample/section-01" resolves to the <section> element in the topic. The key reference is equivalent to the URI reference xref="file.dita#topicid/section-01".

2.2.3.4.4: 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.

A root map might contain any number of key scopes; relationships between key scopes are discussed using the following terms:

child scope: A key scope that occurs directly within another key scope. For example, in the figure below, key scopes "A-1" and "A-2" are child scopes of key scope "A".
parent scope: A key scope that occurs one level above another key scope. For example, in the figure below, key scope "A" is a parent scope of key scopes "A-1" and "A-2".
ancestor scope: A key scope that occurs any level above another key scope. For example, in the figure below, key scopes "A" and "Root" are both ancestor scopes of key scopes "A-1" and "A-2"
descendant scope: A key scope that occurs any level below another key scope. For example, in the figure below, key scopes "A", "A-1", and "A-2" are all descendant scopes of the implicit, root key scope
sibling scope: A key scope that shares a common parent with another key scope. For example, in the figure below, key scopes "A" and "B" are sibling scopes; they both are children of the implicit, root key scope.
key scope hierarchy: A key scope and all of its descendant scopes.

A key scope hierarchy

Keys that are defined in parent key scopes

The key space that is associated with a key scope also includes all key definitions from its parent key scope. If a key name is defined in both a key scope and its parent scope, the key definition in the parent scope takes precedence. This means that a key definition in a parent scope overrides all definitions for the same key name in all descendant scopes. This enables map authors to override the keys that are defined in submaps, regardless of whether the submaps define key scopes.

In certain complex cases, a scope-qualified key name (such as "scope.key") can override an unqualified key name from the parent scope. See Example: How key scopes affect key precedence.

Keys that are defined in child key scopes

The key space associated with a key scope does not include the unqualified key definitions from the child scopes. However, it does include scope-qualified keys from the child scopes. This enables sibling key scopes to have different key definitions for the same key name.

A scope-qualified key name is a key name, prepended by one or more key scope names and separated by periods. For example, to reference a key "keyName" defined in a child scope named "keyScope", specify keyref="keyScope.keyName".

If a key scope has multiple names, its keys can be addressed from its parent scope using any of the scope names. For example, if a key scope is defined with keyscope="a b c", and it contains a key name of "product", that key can be referenced from the parent scope by keyref="a.product", keyref="b.product", or keyref="c.product"

Because a child scope contributes its scope-qualified keys to its parent scope, and that parent scope contributes its scope-qualified keys to its parent scope, it is possible to address the keys in any descendant scope by using the scope-qualified key name. For example, consider a key scope named "ancestorScope" that has a child scope named "parentScope" which in turn has a child scope named "childScope". The scope "childScope" defines a key named "keyName". To reference the key "keyName" from scope "ancestorScope", specify the scope-qualified key name: keyref="parentScope.childScope.keyName".

Keys that are defined in sibling key scopes

Because a parent key scope contains scope-qualified keys from all of its child scopes, and a child scope inherits all of the key definitions (including scope-qualified keys) from its parent scope, it is possible for a child scope to reference its own scope-qualified keys, as well as those defined by its sibling scopes.

For example, consider two sibling scopes, "scope1" and "scope2". Each scope defines the key "productName". References to "productName" in each scope resolve to the local definition. However, since each scope inherits the scope-qualified keys that are available in their parent scope, either scope can reference "scope1.productName" and "scope2.productName" to refer to the scope-specific definitions for that key.

2.2.3.4.5: 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.

When maps are referenced and the value of the @scope attribute is set to "peer", the implications are that the two maps are managed in tandem, and that the author of the referencing map might have access to the referenced map. Adding a key scope to the reference indicates that the peer map should be treated as a separate deliverable for the purposes of linking.

The keys that are defined by the peer map belong to any key scopes that are declared on the <topicref> element that references that map. Such keys can be referenced from content in the referencing map by using scope-qualified key names. However, processors handle references to keys that are defined in peer maps differently from how they handle references to keys that are defined in submaps.

DITA processors are not required to resolve key references to peer maps. However, if all resources are available in the same processing or management context, processors have the potential to resolve key references to peer maps. There might be performance, scale, and user interface challenges in implementing such systems, but the ability to resolve any given reference is ensured when the source files are physically accessible.

Note the inverse implication; if the peer map is not available, then it is impossible to resolve the key reference. Processors that resolve key references to peer maps should provide appropriate messages when a reference to a peer map cannot be resolved. Depending on how DITA resources are authored, managed, and processed, references to peer maps might not be resolvable at certain points in the content life cycle.

The peer map might specify @keyscope on its root element. In that case, the @keyscope on the peer map is ignored for the purpose of resolving scoped key references from the referencing map. This avoids the need for processors to have access to the peer map in order to determine whether a given key definition comes from the peer map.

Example: A root map that declares a peer map

Consider the DITA maps map-a.ditamap and map-b.ditamap. Map A designates Map B as a peer map by using the following markup:

<map>
  <title>Map A</title>
  <topicref 
    scope="peer"
    format="ditamap"
    keyscope="map-b"
    href="../map-b/map-b.ditamap"
    processing-role="resource-only"
  />
  <!-- ... -->
</map>

In this example, map-b.ditamap is not a submap of Map A; it is a peer map.

Example: Key resolution in a peer map that contains a @keyscope attribute on the root element

Consider the map reference in map Map A:

<mapref 
  keyscope="scope-b"
  scope="peer"  
  href="map-b.ditamap"
/>

where map-b.ditamap contains the following markup:

<map keyscope="product-x">
 <!-- ... -->
</map>

From the context of Map A, key references of the form "scope-b.somekey" are resolved to keys that are defined in the global scope of map B, but key references of the form "product-x.somekey" are not. The presence of a @keyscope attribute on the <map> element in Map B has no effect. A key reference to the scope "scope-b.somekey" is equivalent to the unscoped reference "somekey" when processed in the context of Map B as the root map. In both cases, the presence of @keyscope on the root element of Map B has no effect; in the first case it is explicitly ignored, and in the second case the key reference is within the scope "product-x" and so does not need to be scope qualified.

2.2.3.4.6: 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 of undefined keys

If both @keyref and @href attributes are specified on an element, the @href value MUST be used as a fallback address when the key name is undefined. If both @conkeyref and @conref attributes are specified on an element, the @conref value MUST be used as a fallback address when the key name is undefined.

Determining effective attributes on the key-referencing element

The attributes that are common to the key-defining element and the key-referencing element, other than the @keys, @processing-role, and @id attributes, are combined as for content references, including the special processing for the @xml:lang, @dir, and @translate attributes. There is no special processing associated with either the @locktitle or the @lockmeta attributes when attributes are combined.

Keys and conditional processing

The effective key definitions for a key space might be affected by conditional processing (filtering). Processors SHOULD perform conditional processing before determining the effective key definitions. However, processors might determine effective key definitions before filtering. Consequently, different processors might produce different effective bindings for the same map when there are key definitions that might be filtered out based on their filtering attributes.

Note

In order to retain backwards compatibility with DITA 1.0 and 1.1, the specification does not mandate a processing order for different DITA features. This makes it technically possible to determine an effective key definition, resolve references to that key definition, and then filter out the definition. However, the preferred approach is to take conditional processing into account when resolving keys, so that key definitions which are excluded by processing are not used in resolving key references.

Reusing a topic in multiple key scopes

If a topic that contains key references is reused in multiple key scopes within a given root map such that its references resolve differently in each use context, processors MUST produce multiple copies of the source topic in resolved output for each distinct set of effective key definitions that are referenced by the topic. In such cases, authors can use the @copy-to attribute to specify different source URIs for each reference to a topic.

Error conditions

If a referencing element contains a key reference with an undefined key, it is processed as if there were no key reference, and the value of the @href attribute is used as the reference. If the @href attribute is not specified, the element is not treated as a navigation link. If it is an error for the element to be empty, an implementation MAY give an error message; it also MAY recover from this error condition by leaving the key reference element empty.

2.2.3.4.7: 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.

When a key definition is bound to a resource that is addressed by the @href or @keyref attributes, and does not specify "none" for the @linking attribute, all references to that key definition become links to the bound resource. When a key definition is not bound to a resource or specifies "none" for the @linking attribute, references to that key definition do not become links.

When a key definition has no @href value and no @keyref value, references to that key will not result in a link, even if they do contain an @href attribute of their own. If the key definition also does not contain a <topicmeta> subelement, empty elements that refer to the key (such as <link keyref="a"/> or <xref keyref="a" href="fallback.dita"/>) are ignored.

The <object> element has additional key-referencing attributes (@archivekeyrefs, @classidkeyref, @codebasekeyref, and @datakeyref). Key names in these attributes are resolved using the same processing that is described for the normal @keyref attribute.

2.2.3.4.8: 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.

For topic references that use the @keyref attribute, the effective value of the <topicref> element is determined in the following way:

Determining the effective resource

The effective resource bound to the <topicref> element is determined by resolving all intermediate key references. Each key reference is resolved either to a resource addressed directly by URI reference in an @href attribute, or to no resource. Processors MAY impose reasonable limits on the number of intermediate key references that they will resolve. Processors SHOULD support at least three levels of key references.

Note

This rule applies to all topic references, including those that define keys. The effective bound resource for a key definition that uses the @keyref attribute cannot be determined until the key space has been constructed.

Combining metadata

Content from a key-defining element cascades to the key-referencing element following the rules for combining metadata between maps and other maps and between maps and topics. The @lockmeta attribute is honored when metadata content is combined.

The combined attributes and content cascade from one map to another or from a map to a topic, but this is controlled by existing rules for cascading, which are not affected by the use of key references.

If, in addition to the @keys attribute, a key definition specifies a @keyref attribute that can be resolved after the key resolution context for the key definition has been determined, the resources bound to the referenced key definition take precedence.

2.2.3.4.9: 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.

Note

The processing described in this topic is unrelated to the @conkeyref attribute. In that case @conkeyref is used to determine the target of a @conref attribute, after which the normal @conref rules apply.

Empty elements that include a key reference with a defined key might get their effective content from the key definition. Empty elements are defined as elements that meet the following criteria:

Have no text content, including white space
Have no sub-elements
Have no attributes that would be used as text content (such as @alt on the <image> element)

When an empty element as defined above references a key definition that has a child <topicmeta> element, content from that <topicmeta> element is used to determine the effective content of the referencing element. Effective content from the key definition becomes the element content, with the following exceptions:

For empty <image> elements, effective content is used as alternate text, equivalent to creating an <alt> sub-element to hold that content.
For empty <link> elements, effective content is used as link text, equivalent to creating a <linktext> sub-element to hold that content.
For empty <link> and <xref> elements, a key definition can be used to provide a short description in addition to the normal effective content. If the key definition includes <shortdesc> inside of <topicmeta>, that <shortdesc> should be used to provide effective content for a <desc> sub-element.
The <longdescref> and <longquoteref> elements are empty elements with no effective content. Key definitions are not used to set effective text for these elements.
The <param> element does not have any effective content, so key definitions do not result in any effective content for <param> elements.
The <indextermref> element is not completely defined, so determining effective content for this element is also left undefined.
The <abbreviated-form> element is an empty element with special rules that determine its effective content.

Effective text content is determined using the following set of rules:

For the <abbreviated-form> element, see the rules described in <abbreviated-form>
For elements that also exist as a child of <topicmeta> in the key definition, effective content is taken from the first matching direct child of <topicmeta>. For example, given the following key definition, an empty <author> element with the attribute keyref="justMe" would result in the matching content "Just M. Name":
```
<keydef keys="justMe" href="http://www.example.com/my-profile" format="html" scope="external">
  <topicmeta>
    <author>Just M. Name</author>
  </topicmeta>
</keydef>
```
For elements that do not allow the @href attribute, content is taken from the first <keyword> element inside of <keywords> inside of the <topicmeta>. For example, given the following key definition, empty <keyword>, <term>, and <dt> elements with the attribute keyref="nohref" would all result in the matching content "first":
```
<keydef keys="nohref">
  <topicmeta>
    <keywords><keyword>first</keyword><keyword>second</keyword><keyword>third</keyword></keywords>
  </topicmeta>
</keydef>
```
For elements that do allow @href, elements from within <topicmeta> that are legal within the element using @keyref are considered matching text. For example, the <xref> element allows @href, and also allows <keyword> as a child. Using the code sample from the previous item, an empty <xref> with keyref="nohref" would use all three of these elements as text content; after processing, the result would be equivalent to:
```
<xref keyref="test"><keyword>first</keyword><keyword>second</keyword><keyword>third</keyword></xref>
```
Otherwise, if <linktext> is specified inside of <topicmeta>, the contents of <linktext> are used as the effective content.

Note

Because all elements that get effective content will eventually look for content in the <linktext> element, using <linktext> for effective content is a best practice for cases where all elements getting text from a key definition should result in the same value.
Otherwise, if the element with the key reference results in a link, normal link text determination rules apply as they would for <xref> (for example, using the <navtitle> or falling back to the URI of the link target).

When the effective content for a key reference element results in invalid elements, those elements SHOULD be generalized to produce a valid result. For example, <linktext> in the key definition might use a domain specialization of <keyword> that is not valid in the key reference context, in which case the specialized element should be generalized to <keyword>. If the generalized content is also not valid, a text equivalent should be used instead. For example, <linktext> might include <ph> or a specialized <ph> in the key definition, but neither of those are valid as the effective content for a <keyword>. In that case, the text content of the <ph> should be used.

2.2.3.4.10: Examples of keys

This section of the specification contains examples and scenarios. They illustrate a wide variety of ways that keys can be used.

2.2.3.4.10.1: 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".

2.2.3.4.10.2: 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.

In the following example, a "product-name" key is defined. The key definition contains a child <keyword> element nested within a <keydef>element.

<map>
  <keydef keys="product-name">
    <topicmeta>
     <keywords>
       <keyword>Thing-O-Matic</keyword>
     </keywords>
    </topicmeta>
  </keydef>
</map>

A topic can reference the "product-name" key by using the following markup:

<topic id="topicid">
  <p><keyword keyref="product-name"/> is a product designed to ...</p>
</topic>

When processed, the output contains the text "Thing-O-Matic is a product designed to ... ".

In the following example, the key definition contains both a reference to a resource and variable text.

<map>
  <keydef keys="product-name" href="thing-o-matic.dita">
    <topicmeta>
     <keywords>
       <keyword>Thing-O-Matic</keyword>
     </keywords>
    </topicmeta>
  </keydef>
</map>

When processed using the key reference from the first example, the output contains the "Thing-O-Matic is a product designed to ... " text. The phrase "Thing-O-Matic" also is a link to the thing-o-matic.dita topic.

2.2.3.4.10.3: 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.

The Acme Tractor Company produces two models of tractor: X and Y. Their product manual contains sets of instructions for each model. While most maintenance procedures are different for each model, the instructions for changing the oil are identical for both model X and model Y. The company policies call for including the specific model number in each topic, so a generic topic that could be used for both models is not permitted.

The authoring team references the model information in the changing-the-oil.dita topic by using the following mark-up:
```
<keyword keyref="model"/>
```

The information architect examines the root map for the manual, and decides how to define key scopes. Originally, the map looked like the following:

<map>
  <!-- Model X: Maintenance procedures -->
  <topicref href="model-x-procedures.dita">
    <topicref href="model-x/replacing-a-tire.dita"/>
    <topicref href="model-x/adding-fluid.dita"/>
  </topicref>

<!-- Model Y: Maintenance procedures -->
  <topicref href="model-y-procedures.dita">
    <topicref href="model-y/replacing-a-tire.dita"/>
    <topicref href="model-y/adding-fluid.dita"/>
  </topicref>
</map>

The information architect wraps each set of procedures in a <topicgroup> element and sets the @keyscope attribute.

<map>
  <!-- Model X: Maintenance procedures -->
  <topicgroup keyscope="model-x">
    <topicref href="model-x-procedures.dita">
      <topicref href="model-x/replacing-a-tire.dita"/>
      <topicref href="model-x/adding-fluid.dita"/>
    </topicref>
  </topicgroup>

<!-- Model Y: Maintenance procedures -->
  <topicgroup keyscope="model-y">
    <topicref href="model-y-procedures.dita">
      <topicref href="model-y/replacing-a-tire.dita"/>
      <topicref href="model-y/adding-fluid.dita"/>
    </topicref>
  </topicgroup>
</map>

This defines the key scopes for each set of procedures.

The information architect then adds key definitions to each set of procedures, as well as a reference to the changing-the-oil.dita topic.

<map>
  <!-- Model X: Maintenance procedures -->
  <topicgroup keyscope="model-x">
    <keydef keys="model">
      <topicmeta>
        <linktext>X</linktext>
      </topicmeta>
    </keydef>
    <topicref href="model-x-procedures.dita">
      <topicref href="model-x/replacing-a-tire.dita"/>
      <topicref href="model-x/adding-fluid.dita"/>
      <topicref href="common/changing-the-oil.dita"/>
    </topicref>
  </topicgroup>

<!-- Model Y: Maintenance procedures -->
  <topicgroup keyscope="model-y">
    <keydef keys="model">
      <topicmeta>
        <linktext>Y</linktext>
      </topicmeta>
    </keydef>
    <topicref href="model-y-procedures.dita">
      <topicref href="model-y/replacing-a-tire.dita"/>
      <topicref href="model-y/adding-fluid.dita"/>
      <topicref href="common/changing-the-oil.dita"/>
    </topicref>
  </topicgroup>
</map>

When the DITA map is processed, the changing-the-oil.dita topic is rendered twice. The model variable is rendered differently in each instance, using the text as specified in the scoped key definition. Without key scopes, the first key definition would win, and "model "X" would be used in all topics.

2.2.3.4.10.4: 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.

In the following example, a map contains two definitions for the key "load-toner":

<map>
  <!--... -->
  <keydef keys="load-toner" href="model-1235-load-toner-proc.dita"/>
  <keydef keys="load-toner" href="model-4545-load-toner-proc.dita"
  />
  <!--... -->
</map>

In this example, only the first key definition (in document order) of the "load-toner" key is effective. All references to the key within the scope of the map resolve to the topic model-1235-load-toner-proc.dita.

In the following example, a map contains two definitions for the "file-chooser-dialog" key; each key definition specifies a different value for the @platform attribute.

<map>
  <!--... -->
  <keydef keys="file-chooser-dialog" href="file-chooser-osx.dita" platform="osx"/>
  <keydef keys="file-chooser-dialog" href="file-chooser-win7.dita" platform="windows7"/>
  <!--... -->
</map>

In this case, the effective key definition is determined not only by the order in which the definitions occur, but also by whether the active value of the platform condition is "osx" or "windows7". Both key definitions are potentially effective because they have distinct values for the conditional attribute. Note that if no active value is specified for the @platform attribute at processing time, then both of the key definitions are present and so the first one in document order is the effective definition.

If the DITAVAL settings are defined so that both "osx" and "windows" values for the @platform attribute are excluded, then neither definition is effective and the key is undefined. That case can be avoided by specifying an unconditional key definition after any conditional key definitions, for example:

<map>
  <!--... -->
  <keydef keys="file-chooser-dialog" href="file-chooser-osx.dita" platform="osx"/>
  <keydef keys="file-chooser-dialog" href="file-chooser-win7.dita" platform="windows7"/>
  <keydef keys="file-chooser-dialog" href="file-chooser-generic.dita"/>
  <!--... -->
</map>

If the above map is processed with both "osx" and "windows" values for the @platform attribute excluded, then the effective key definition for "file-chooser-dialog" is the file-chooser-generic.dita resource.

2.2.3.4.10.5: 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.

In the following example, a root map contains a key definition for the key "toner-specs" and references to two submaps.

<map>
  <keydef keys="toner-specs" href="toner-type-a-specs.dita"/>
  <mapref href="submap-01.ditamap"/>
  <mapref href="submap-02.ditamap"/>
</map>

The first submap, submap-01.ditamap, contains definitions for the keys "toner-specs" and "toner-handling":

<map>
  <keydef keys="toner-specs" href="toner-type-b-specs.dita"/>
  <keydef keys="toner-handling" href="toner-type-b-handling.dita"/>
</map>

The second submap, submap-02.ditamap, contains definitions for the keys "toner-specs", "toner-handling", and "toner-disposal":

<map>
  <keydef keys="toner-specs" href="toner-type-c-specs.dita"/>
  <keydef keys="toner-handling" href="toner-type-c-handling.dita"/>
  <keydef keys="toner-disposal" href="toner-type-c-disposal.dita"/>
</map>

For this example, the effective key definitions are listed in the following table.

Key	Bound resource
toner-specs	`toner-type-a-specs.dita`
toner-handling	`toner-type-b-handling.dita`
toner-disposal	`toner-type-c-disposal.dita`

The key definition for "toner-specs" in the root map is effective, because it is the first encountered in a breadth-first traversal of the root map. The key definition for "toner-handling" in submap-01.ditamap is effective, because submap-01 is included before submap-02 and so comes first in a breadth-first traversal of the submaps. The key definition for "toner-disposal" is effective because it is the only definition of the key.

2.2.3.4.10.6: 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.

In the following example, a <topicref> element references the key "widget". The definition for "widget" in turn references the key "mainProduct".

<map>
  <topicref keyref="widget" id="example"/>
  <keydef keys="widget" href="widgetInfo.dita" scope="local" format="dita" rev="v1r2"
          keyref="mainProduct">
    <topicmeta><navtitle>Information about Widget</navtitle></topicmeta>
  </keydef>
  <keydef keys="mainProduct" href="http://example.com/productPage" scope="external" format="html"
          product="prodCode" audience="sysadmin">
    <topicmeta><navtitle>Generic product page</navtitle></topicmeta>
  </keydef>
</map>

For this example, the key reference to "widget" pulls resources from that key definition, which in turn pulls resources from "mainProduct". The metadata resources from "mainProduct" are combined with the resources already specified on the "widget" key definition, resulting in the addition of @product and @audience values. Along with the navigation title, the @href, @scope, and @format attributes on the "widget" key definition override those on "mainProduct". Thus after key references are resolved, the original reference from <topicref> is equivalent to:

<topicref id="example"
          href="widgetInfo.dita" scope="local" format="dita" rev="v1r2"
          product="prodCode" audience="sysadmin">
   <topicmeta><navtitle>Information about Widget</navtitle></topicmeta>
</topicref>

2.2.3.4.10.7: Example: References to scoped keys

You can address scoped keys from outside the key scope in which the keys are defined.

<map xml:lang="en">
  <title>Examples of scoped key references</title>

  <!-- Key scope #1 -->
  <topicgroup keyscope="scope-1">
    <keydef keys="key-1" href="topic-1.dita"/>
    <topicref keyref="key-1"/>
    <topicref keyref="scope-1.key-1"/>
    <topicref keyref="scope-2.key-1"/>
  </topicgroup>

  <!-- Key scope #2 -->
  <topicgroup keyscope="scope-2">
    <keydef keys="key-1" href="topic-2.dita"/>
    <topicref keyref="key-1"/>
    <topicref keyref="scope-1.key-1"/>
    <topicref keyref="scope-2.key-1" />
  </topicgroup>

  <topicref keyref="key-1" />
  <topicref keyref="scope-1.key-1" />
  <topicref keyref="scope-2.key-1" />

</map>

For this example, the effective key definitions are listed in the following tables.

Effective key definitions for scope-1

Key reference	Resource
key-1	`topic-1.dita`
scope-1.key-1	`topic-1.dita`
scope-2.key-1	`topic-2.dita`

Effective key definitions for scope-2

Key reference	Resource
key-1	`topic-2.dita`
scope-1.key-1	`topic-1.dita`
scope-2.key-1	`topic-2.dita`

Effective key definitions for the key scope associated with the root map

Key reference	Resource
key-1	Undefined
scope-1.key-1	`topic-1.dita`
scope-2.key-1	`topic-2.dita`

2.2.3.4.10.8: 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.

Consider the following DITA map:

<map>
  <title>Root map</title>
  <!-- Root scope -->
  <keydef keys="a" href="topic-1.dita"/>
  
  <!-- Key scope A -->
  <topicgroup keyscope="A">
    <keydef keys="b" href="topic-2.dita"/>
    
    <!-- Key scope A-1 -->
    <topicgroup keyscope="A-1">
      <keydef keys="c" href="topic-3.dita"/>
    </topicgroup>

    <!-- Key scope A-2 -->    
    <topicgroup keyscope="A-2">
      <keydef keys="d" href="topic-4.dita"/>
    </topicgroup>
  </topicgroup> 

  <!-- Key scope B -->  
  <topicgroup keyscope="B">
    <keydef keys="a" href="topic-5.dita"/>
    <keydef keys="e" href="topic-6.dita"/>

    <!-- Key scope B-1 -->     
    <topicgroup keyscope="B-1">
      <keydef keys="f" href="topic-7.dita"/>
    </topicgroup>

    <!-- Key scope B-2 -->
    <topicgroup keyscope="B-2">
      <keydef keys="g" href="topic-8.dita"/>
    </topicgroup>
  </topicgroup>
</map>

The key scopes in this map form a tree structure.

Graphical representation of the key scopes

Tree structure diagram showing example references to key scope names relative to other key scopes. The tree has a root node labeled 'Root' with two children 'A' and 'B', which in turn have children 'A-1', 'A-2', 'B-1', and 'B-2'. Every node has a list of one or more key scope names with different typographic styling. In the root node the name 'A' appears with no style, and the following labels appear with parentheses: 'A.b', 'A.A-1.c', 'A.A-2.d', 'B.a', 'B.e', 'B.B-1.f', 'B.B-2.g'. In the A node the name 'b' has no style, and the following labels appear with parentheses: 'A-1.c', 'A-2.d'. In the A-1 node the label 'c' appears with no style. In the A-2 node the label 'd' appears with no style. In the B node the label 'a' appears with square brackets; the label 'e' appears with no style; and the following labels appear with parentheses: 'B-1.f', 'B-2.g'. In the B-1 node the label 'f' appears with no style. In the B-2 node the label 'g' appears with no style.

Each box in the diagram represents a key scope; the name of the key scope is indicated in bold with upper-case letters. Below the name of the key scope, the key definitions that are present in the scope are listed. Different typographic conventions are used to indicate where the key definition occurs:

No styling: The key definition occurs in the immediate key scope and is not overridden by a key definition in a parent scope. For example, key "a" in the root map.
Parentheses: The key definition occurs in a child scope. For example, keys "A-1.c" and "A-2.d" in key scope A.
Brackets: The key definition occurs in the immediate key scope, but it is overridden by a key definition in an ancestor scope. For example, key "a" in key scope B.

Arrows point from child to parent scopes.

Assume that each key scope contains numerous key references. The following tables demonstrate how key references resolve in key scopes A-2 and B. The first column shows the value used in key references; the second column shows the resource to which the key resolves.

Key scope A-2

Key reference	Resource to which the key resolves
a	"a", defined in the root map: `topic-1.dita`
d	"d", as defined in the immediate key scope: `topic-4.dita`
A-2.d	"d", as defined in the immediate key scope: `topic-4.dita`
c	Undefined
A-1.c	"A-1.c", as defined in key scope A-1. This key name is available because it exists in the parent scope, key scope A. The key name resolves to `topic-3.dita`
A.A-1.c	"A-1.c", as defined in key scope A-1. This key name is available because it exists in the root key scope. The key name resolves to `topic-3.dita`

Key scope B

Key reference	Resource to which the key resolves
e	"e", defined in the immediate key scope: `topic-6.dita`
a	"a", as defined in the root key scope. (While a key definition for "a" exists in the immediate key scope, it is overridden by the key definition that occurs in the parent key scope.) The key name resolves to `topic-1.dita`
B.a	"a", as defined in the immediate key scope. Because the key reference uses the scope-qualified names, it resolves to the key "a" in scope B. The key name resolves to `topic-5.dita`
g	Undefined. The key "g" is defined only in key scope B-2, so no unqualified key named "g" is defined in scope B.
B-2.g	"g", as defined in key scope B-2: `topic-8.dita` .

2.2.3.4.10.9: 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.

A company wants to use a common DITA topic for information about recycling: recycling.dita. However, the topic contains a cross-reference to a topic that needs to be unique for each product line; each such topic contains product-specific URLs.

The editing team creates a recycling.dita topic that includes a cross-reference to the product-specific topic. The cross reference is implemented using a key reference:
```
<xref keyref="product-recycling-info" href="generic-recycling-info.dita"/>
```
The value of the @href attribute provides a fallback in the event that a product team forgets to include a key definition for "product-recycling-info".
Each product documentation group creates a unique key definition for "product-recycling-info". Each group authors the key definition in a DITA map, for example:
```
<map>
  
  <keydef keys="product-recycling-info" href="acme-server-recycling.dita"/>
  
</map>
```
Each team can use the recycling.dita topic, and the cross reference in the topic resolves differently for each team.
A year later, there is an acquisition. The newly-acquired team wants to reuse Acme's common material, but it needs to direct its users to an external Web site that lists the URLs, rather than a topic in the product documentation. Their key definition looks like the following:
```
<topicref  keys="product-recycling-info" 
                  href="http://acme.example.com/server/recycling" 
                  scope="external" format="html"/>
 
```
When newly-acquired team uses the recycling.dita topic, it resolves to the external Web site; however for all other teams, the cross reference in the topic continues to resolves to their product-specific topic.
A new product team is formed, and the team forgets to include a key definition for "product-recycling-info" in one of their root maps. Because the cross reference in the recycling.dita topic contains a value for the @href attribute, the link falls back to generic-recycling-info.dita, thus avoiding a broken cross reference in the output.

2.2.3.4.10.10: Example: Link modification or removal

This scenario outlines how different authors can effectively remove or modify a <link> element in a shared topic.

A company wants to use a shared topic for information about customer support. For most products, the shared topic should include a link to a topic about extended warranties. But a small number of products do not offer extended warranties.

Team one creates the shared topic: customer-support.dita. The topic contains the following mark-up:
```
 <related-links>
  <link keyref="extended-warranties" href="common/extended-warranties.dita"/>
 </related-links>
```
The teams that need the link to the topic about extended warranties can reference the customer-support.dita topic in their DITA maps. When processed, the related link in the topic resolves to the common/extended-warranties.dita topic.
The teams that do not want the related link to the topic about extended warranties can include a key definition in their DITA map that does not include an @href attribute, for example:
```
<map>
  
  <keydef keys="extended-warranties"/>
  
</map>
```
When processed, the related link in the topic is not rendered.
Yet another team wants to simply have a paragraph about extended warranties printed. They define the key definition for "extended-warranties" as follows:
```
<map>
  
  <keydef keys="extended-warranties"/>
    <topicmeta>
      <linktext>This product does not offer extended warranties.</linktext>
    </topicmeta>
  
</map>
```
When this team renders their content, there is no hyperlink in the output, just the text "This product does not offer extended warranties" statement.

2.2.3.4.10.11: 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.

In this scenario, a company with well-developed glossary wants to ensure that instances of a term that is defined in the glossary always include a link to the glossary topic.

An information architect adds values for the @keys attribute to all the of the <topicref> elements that are in the DITA map for the glossary, for example:

<map>
  <title>Company-wide glossary</title>
  <topicref keys="term-1" href="term-1.dita"/>
  <topicref keys="term-2" href="term-2.dita"/>
  <topicref keys="term-3" href="term-3.dita"/>
  <topicref keys="term-4" href="term-4.dita"/>
</map>

When authors refer to a term in a topic, they use the following mark-up:
```
<term keyref="term-1"/>
```
When the <term> element is rendered, the content is provided by the <title> element of the glossary topic. The <term> element also is rendered as a link to the glossary topic.

2.2.3.4.10.12: 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.

In this scenario, Acme produces content for a product that is also resold through a business partner. When the DITA content is published for the partner, several items must be different, including the following:

Product names
Standard notes that contain admonitions

Simply using the @conref attribute would not be possible for teams that use a component content management system where every DITA topic is addressed by a globally-unique identifier (GUID).

Authors reference the reusable content in their topics by using the @conkeyref attribute, for example:

<task id="reusable-product-content">
  <title><keyword conkeyref="reuse/product-name"/> prerequisites</title>
  <taskbody>
    <prereq><note conkeyref="reuse/warning-1"/></prereq>
    <!-- ... -->
  </taskbody>
</task>

Authors create two different topics; one topic contains elements appropriate for Acme, and the other topic contains elements appropriate for the partner. Note that each reuse topic must use the same element types (or compatible specializations) and values for the @id attribute. For example, the following reuse file is appropriate for use by Acme:
```
<topic id="acme-reuse">
  <title>Reuse topic for Acme</title>
  <body>
    <note id="warning-1">Admonitions for Acme</note>
    <p><keyword id="product-name">Acme product name</keyword></p>
    
  </body>
</topic>
```
The following reuse file is appropriate for use by the OEM partner:
```
<topic id="oem-reuse">
  <title>Reuse topic for OEM partner</title>
  <body>
    <note id="warning-1">Admonitions for partner</note>
    <p><keyword id="product-name">OEM product name</keyword></p>
    
  </body>
</topic>
```
The two versions of the DITA maps each contain different key definitions for the key name "reuse". (This associates a key with the topic that contains the appropriate reusable elements.) For example:
DITA map for Acme
```
<map>
  
  <keydef keys="reuse" href="acme-reuse.dita"/>
  
</map>
```
DITA map for OEM partner
```
<map>
  
  <keydef keys="reuse" href="oem-reuse.dita"/>
  
</map>
```

When each of the DITA maps is published, the elements that are referenced by @conkeyref will use the reuse topic that is referenced by the <keydef> element in the map. The product names and warnings will be different in the output.

2.2.3.4.10.13: 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.

In this scenario, a training organization wants to produce a deliverable that includes all of their training course materials. Each course manual uses common keys for standard parts of the course materials, including "prerequisites," "overview", "a

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

OASIS Standard

0

os

17 December 2015

DITA Version 1.3 Specification Draft

part3-all-inclusive

Specification URIs

This version

Previous version

Latest version

Technical Committee

Chair

Editors

Additional artifacts

Abstract

Status

Citation format

Notices

Chapter 1: Introduction to DITA 1.3

1.1.1: About the DITA specification: All-inclusive edition

All-inclusive edition

XML grammar files

DITA written specification

1.1.2: Terminology

1.1.3: Normative references

1.1.4: Non-normative references

1.1.5: Formatting conventions in the XHTML version of the specification

Link previews

Link previews

Navigation links

Navigation links

Chapter 2: Architectural specification: All-inclusive edition

2.2.1: Introduction to DITA

2.2.1.1: DITA terminology and notation

Notation

Normative and non-normative information

Basic DITA terminology

Specialization terminology

DITA modules

Linking and addressing terms

Terminology related to keys

Map terms

2.2.1.2: Basic concepts

2.2.1.3: File extensions

2.2.1.4: Producing different deliverables from a single source

2.2.2: DITA markup

2.2.2.1: DITA topics

2.2.2.1.1: The topic as the basic unit of information

2.2.2.1.2: The benefits of a topic-based architecture

2.2.2.1.3: Disciplined, topic-oriented writing

Conciseness and appropriateness

Locational independence

Navigational independence

2.2.2.1.4: Information typing

2.2.2.1.5: Generic topics

2.2.2.1.6: Topic structure

2.2.2.1.7: Topic content

2.2.2.2: DITA maps

2.2.2.2.1: Definition of DITA maps

2.2.2.2.2: Purpose of DITA maps

2.2.2.2.3: DITA map elements

2.2.2.2.4: DITA map attributes

Note

Note

Note

2.2.2.2.5: Examples of DITA maps

2.2.2.2.5.1: Example: DITA map that references a subordinate map

2.2.2.2.5.2: Example: DITA map with a simple relationship table

2.2.2.2.5.3: Example: How the @collection-type and @linking attributes determine links

Simple linking example

Linking example with the @linking attribute

2.2.2.2.5.4: Example: How the @cascade attribute functions

2.2.2.3: Subject scheme maps and their usage

2.2.2.3.1: Subject scheme maps

2.2.2.3.2: Defining controlled values for attributes

Example: Controlled values that provide additional information about the subject

2.2.2.3.3: Binding controlled values to an attribute

Example: Binding a list of controlled values to the @audience attribute

Example: Binding an attribute to an empty set

`test-2.ditamap`

`b.ditamap`