data

Darwin Information Typing Architecture (DITA) Version 1.3 Part 2: Technical Content Edition

version
1.3
author
OASIS DITA Technical Committee

The data element represents a property within a DITA topic or map. While the data element can be used directly to capture properties, it is particularly useful as a basis for specialization. Default processing should treat the content as an unknown kind of metadata and ignore it for rendering, but custom processing might match the name attribute or specialized element and use the element for automated manipulation or to format data associated with the body flow. For example, a specialized data element might be used to format properties as sidebars or other adornments or to harvest properties for automated processing.

The subject of the property is ordinarily the container of the data element. In the content model for the prolog and metadata elements, the property applies to the topic as a whole. In the topicmeta element, the property applies to the referenced topic. The data-about element can be used to identify the subject of the property with an explicit reference.

The name attribute names the property for processes. A title subelement can provide a label for the property. The datatype attribute can be used to identify the type for the value. The value of the property can be any of the following:

  • A simple text value expressed with the value attribute or textual content.
  • A reference to either DITA content or a non-DITA resource expressed with the href attribute.
  • An image or other non-textual object.
  • A brief unit of descriptive text that is not part of the body text flow.
  • A complex structure composed of nested data elements.
CAUTION:
Processors should ignore the content of the data element by default, so the data element should only be used for properties and not to embed text for formatting as part of the flow of the topic body. It might be tempting to specialize the data element for text that is part of the body flow, so as to escape the restrictions of the base content models. This abuse of the DITA architecture will cause problems. For example, if a particular kind of paragraph is specialized from data rather than from p, then when the content is exchanged with others that do not recognize the specialized element, their processors will skip the content.

The data element can be nested to create structures for complex properties. The name attribute might be used to distinguish different semantics associated with different instances of the data element such as addresses, times, amounts, and so on. In many cases, however, it is preferable to specialize the data element for more precise semantics, structures, and values. For instance, a specialization can specify an enumeration for the value attribute.

A data element containing properties of a topic as a whole should be located in the topic's prolog or metadata element, or in a topicmeta element related to a topicref that references the topic. The data element generally goes at the beginning of the element to which the properties in it refer. Where this is unwieldy, the data element can go in the prolog, with the data-about element identifying which specific element in the topic is the reference.

Content models

See appendix for information about this element in OASIS document type shells.

Inheritance

- topic/data

Example

Uses of the data element can include the following:

  • Complex metadata properties such as bibliographic records corresponding to citations.
  • Hybrid documents with data values as part of the content, such as word processor formats using form fields.
  • Messages in which the payload includes human-readable content. Such applications can use the data element to define the addressing on the message envelope. For instance, a topic could model an email message by representing the address with specialized data elements in the prolog element and the content with the body element.
  • Transactional documents in which the values are processed but also displayed with human-readable content. In particular, a library of building blocks for transaction documents can be implemented through a DITA domain as specialized data elements including those from the UN/CEFACT Core Components Technical Specification (http://www.unece.org/cefact/).
Figure. Using the name attribute on unspecialized data elements

This structure identifies the library and version demonstrated by a code sample. The name attribute is used to identify both the grouping data element and the nested data elements that provide specific properties. These properties will not appear in the output unless a processor is customized to recognize these name attribute values.

<codeblock>
  <data name="exampleOf">
    <data name="library" href="ajaxLibrary.js"/>
    <data name="version" value="2006-6-19"/>
  </data>
  <!-- ... -->
</codeblock>
Figure. Specializing data to annotate a code sample

The following example specifies the delimited source code for a code fragment so an automated process can refresh the code fragment. The fragmentSource, sourceFile, startDelimiter, and endDelimiter elements are specialized from data but the codeFragment is specialized from codeblock. The properties specialized from data would not appear in formatted output unless a processor is explicitly instructed to display them:

<example>
    <title>An important coding technique</title>
    <codeFragment>
        <fragmentSource>
            <sourceFile     value="helloWorld.java"/>
            <startDelimiter value="FRAGMENT_START_1"/>
            <endDelimiter   value="FRAGMENT_END_1"/>
        </fragmentSource>
        <!-- ... -->
    </codeFragment>
</example>
Figure. Specializing data to annotate housing information

The following example identifies a real estate property as part of a house description. The realEstateProperty element and its child elements are specialized from data. The houseDescription element is specialized from section. A specialized process can format the values as part of a brochure if they meet criteria for inclusion.

<houseDescription>
  <title>A great home for sale</title>
  <realEstateProperty>
    <realEstateBlock value="B7"/>
    <realEstateLot   value="4003"/>
    <!-- ... -->
  </realEstateProperty>
  <p>This elegant....</p>
  <object data="B7_4003_tour360Degrees.swf"/>
</houseDescription>

Attributes

The following attributes are available on this element: Data element attributes group, Link relationship attribute group, Universal attribute group, keyref, and outputclass.