`<data>`

Data is a generic component that represents metadata within a topic or map. Complex metadata is represented by nested data structures.

Usage information

The primary purpose of the <data> element is as a specialization base. Because it can nest, it can be used to create complex metadata structures. It is available in both block and inline contexts, which allows the <data> element to specify properties for most element types.

A metadata property specified using a <data> element usually applies to the structure that contains the <data> element.

When located in <prolog> and <metadata> elements, the property applies to the topic as a whole. When located in the <topicmeta> element, the property applies to the referenced topic.

Important (non-normative):

By default, processors do not render the content of the <data> element. Use the <data> element only for properties; do not use it to embed text as part of the content flow.

Rendering expectations

By default, processors SHOULD treat a <data> element as unknown metadata. The contents of the <data> element SHOULD NOT be rendered.

Processors that recognize a particular <data> element MAY make use of it to trigger specialized rendering.

Content model

Zero or more

Attributes

The following attributes are available on this element: data-element attributes, link-relationship attributes, universal attributes, and @keyref.

The following attributes are available on this element: universal attributes and the attributes defined below.

@datatype (data-element attributes): Specifies the type of data contained in the @value attribute or within the <data> element. A typical use of @datatype will be the identifying URI for an XML Schema datatype.
@format (link-relationship attributes): Specifies the format of the resource that is referenced. See The format attribute for detailed information on supported values and processing implications.
@href (link-relationship attributes): Specifies a reference to a resource. See The href attribute for detailed information on supported values and processing implications.
@keyref: Specifies a key name that acts as a redirectable reference based on a key definition within a map. See The keyref attribute for information on using this attribute.
For HDITA, the equivalent of @keyref is @data-keyref
@name (data-element attributes): Defines a unique name for the object.
@scope (link-relationship attributes): Specifies the closeness of the relationship between the current document and the referenced resource. The following values are valid: local, peer, external, and -dita-use-conref-target.
See The scope attribute for detailed information on supported values and processing implications.
@type (link-relationship attributes): Describes the target of a reference. See The type attribute for detailed information on supported values and processing implications.
@value (data-element attributes): Specifies a value associated with the current property or element.

Examples

This section is non-normative.

This section contains examples of how the <data> element can be used.

Example 1. Using the @name attribute on unspecialized <data> elements

The following code sample shows how the <data> element can be used to provide metadata. Rendering tools that recognize this metadata can automatically apply highlighting to the code.

<codeblock>
  <data name="codestyle" value="javascript"/>
  <!-- JavaScript code block -->
</codeblock>

Example 2. Nesting <data> elements for complex metadata

The following code sample shows how nested <data> elements can provide complex inventory metadata for a part that is described in the topic:

<topic id="sample">
  <title>How to purchase items from the warehouse</title>
  <prolog>
    <data name="inventory">
      <data name="aisle" value="4"/>
      <data name="bin" value="13"/>
      <data name="restock" value="weekly"/>
    </data>
  </prolog>
  <body>
    <!-- ... -->
  </body>
</topic>

Example 3. Specializing <data> for structured metadata

The following code sample contains specializations of the <data> element: <change-item>, <change-completed>, and <change-summary>. These specialized elements each provide a default for @name inside the grammar files, so that processors can work with the data without authors having to specify the attribute.

<topic id="data">
  <title><xmlelement>data</xmlelement></title>
  <prolog>
    <change-historylist>
      <change-item>
        <change-completed>2017-08-20</change-completed>
        <change-summary>Refactored topic to use new template</change-summary>
      </change-item>
      <change-item>
        <change-completed>2018-06-06</change-completed>
        <change-summary>Created new examples</change-summary>
      </change-item>
    </change-historylist>
  </prolog>
  <body>
    <!-- ... -->
  </body>
</topic>