Defining controlled values for attributes

Subject scheme maps can define controlled values for DITA attributes without having to define specializations or constraints. The list of available values can be modified quickly to adapt to new situations.

Each controlled value is defined using a <subjectdef> element, which is a specialization of the <topicref> element. The <subjectdef> element is used to define both a subject category and a list of controlled values. The parent <subjectdef> element defines the category, and the children <subjectdef> elements define the controlled values.

The subject definitions can include additional information within a <topicmeta> element to clarify the meaning of a value:
  • A <navtitle> (or a <titlealt> element with a @title-role of navigation) can provide a more readable name for the controlled value.
  • The <shortdesc> element can provide a definition.

In addition, the <subjectdef> element can reference a more detailed definition of the subject, for example, another DITA topic or an external resource.

The following behavior is expected of processors in regard to subject scheme maps:
  • Authoring tools SHOULD use these lists of controlled values to provide lists from which authors can select values when they specify attribute values.
  • Authoring tools MAY give an organization a list of readable labels, a hierarchy of values to simplify selection, and a shared definition of the value.
  • Authoring tools MAY support accessing and displaying the content of the subject definition resource in order to provide users with a detailed explanation of the subject.

Example: Controlled values that provide additional information about the subject

This section is non-normative.

The following code sample illustrates how a subject definition can provide a richer level of information about a controlled value:

<subjectdef keys="terminology" href="https://www.oasis-open.org/policies-guidelines/keyword-guidelines">
  <subjectdef keys="rfc2119" href="rfc-2119.dita">
    <topicmeta>
      <navtitle>RFC-2119 terminology</navtitle>
      <shortdesc>The normative terminology that the DITA TC uses for the DITA specification</shortdesc>
    </topicmeta>
  </subjectdef>
  <subjectdef keys="iso" href="iso-terminology.dita">
    <topicmeta>
      <navtitle>ISO keywords</navtitle>
      <shortdesc>The normative terminology used by some other OASIS technical committees
      </shortdesc>
    </topicmeta>
  </subjectdef>
</subjectdef>

The content of the <navtitle> and <shortdesc> elements provide additional information that a processor might display to users as they select attribute values or classify content. The resources referenced by the @href attributes provide even more detailed information. A processor might render expandable links as part of a user interface that implements a progressive disclosure strategy, or an authoring tool might include the navigation title and short description in a window where the user selects a controlled value.