`<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. Since it is available in both block and inline contexts, the <data> element can 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.

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

Attributes

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

Examples

Figure 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>

Figure 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>

Figure 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>