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.
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.
See appendix for information about this element in OASIS document type shells.
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/).
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>
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>
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>