<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

(Text | <audio> | <cite> | <include> | <keyword> | <ph> | <strong> | <em> | <b> | <i> | <line-through> | <overline> | <sup> | <sub> | <tt> | <u> | <q> | <term> | <text> | <tm> | <xref> | <data> | <sort-as> | <draft-comment> | <foreign> | <image> | <object> | <required-cleanup> | <title> | <video> )*

Contained by

<abstract> , <alt> , <author> , <b> , <body> , <bodydiv> , <brand> , <category> , <cite> , <component> , <consequence> , <coords> , <copyrholder> , <data> , <dd> , <ddhd> , <desc> , <div> , <dl> , <draft-comment> , <dt> , <dthd> , <em> , <entry> , <example> , <fallback> , <featnum> , <fig> , <figgroup> , <fn> , <i> , <include> , <index-see> , <index-see-also> , <indexterm> , <li> , <line-through> , <lines> , <linkinfo> , <linktext> , <linktitle> , <lq> , <messagepanel> , <metadata> , <navtitle> , <note> , <ol> , <overline> , <p> , <ph> , <platform> , <pre> , <prodname> , <prognum> , <prolog> , <publisher> , <q> , <resourceid> , <searchtitle> , <section> , <series> , <shortdesc> , <sl> , <sli> , <source> , <stentry> , <strong> , <sub> , <subtitle> , <sup> , <title> , <titlealt> , <titlehint> , <tt> , <typeofhazard> , <u> , <ul> , <xref>

Zero or more of the following

Contained by

Inheritance

- topic/data

The <data> element is a base element type. It is defined in the topic module.

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.
@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>