DITA metadata

Metadata elements are available in both topics and DITA maps. This design enables authors and information architects to use identical metadata markup in both topics and maps.

When used in maps, metadata elements are located in the <topicmeta> element. When used in topics, metadata elements are located in the <prolog> element.

In general, specifying metadata in a <topicmeta> element that is a child of a <topicref> element is equivalent to specifying it in the <prolog> element of the referenced topic. The value of specifying the metadata in the map is that the topic then can be reused in other maps where different metadata might apply. Many items in the <topicmeta> element cascade to nested <topicref> elements within the map. See Reconciling topic and map metadata elements for information about which elements cascade.

Metadata attributes specify properties of the content that can be used to determine how the content is 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

The base DITA vocabulary includes five specializations of the @props attribute as domains: @audience, @deliveryTarget, @platform, @product, and @otherprops. These five attributes are included in all the map and topic document-type shells that are provided with the specification.

Metadata attributes fall into the following categories.

Architectural attributes

The @class, @DITAArchVersion, and @specializations attributes provide metadata about the DITA source itself, such as what version of the grammar is used. These attributes are not intended for use in authored content.

Filtering and flagging attributes

The @props attribute and its specializations are intended for filtering. This includes the five specializations added to the OASIS document-type shells: @audience, @deliveryTarget, @platform, @product, and @otherprops.

These attributes plus the @rev attribute are intended for flagging.

Other metadata attributes

The @status and @importance attributes, many of the attributes available on the <ux-window> element, as well as custom attributes specialized from @base, are intended for application-specific behaviors. Such behaviors include aiding in search and retrieval, as well as controlling how a user assistance window is rendered.

Translation and localization attributes

The @dir, @translate, and @xml:lang attributes are intended for use with translating and localizing content.

Metadata can be specified in both maps and topics. In most cases, metadata in the map either supplements or overrides metadata that is specified at the topic level.

Metadata elements and attributes in a map might apply to an individual topic, a set of topics, or globally for the entire document. Most metadata elements authored within a <topicmeta> element associate 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 metadata for a set of 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 is that the map author has more knowledge of the reusing context than the topic author.

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.

In some help systems, a topic might need to be displayed in a window with a specific size or set of features. 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.

Application metadata that is specified on the <ux-window> element is closely tied to that specific application. It might be ignored when content is rendered for other uses.