Defining controlled values for attributes
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:
- The <navtitle> element can provide a more readable value name.
- 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:
- 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.
- An editor MAY support accessing and displaying the content of the subject definition resource in order to provide users with a detailed explanation of the subject.
- Tools MAY produce a help file, PDF, or other readable catalog to help authors better understand the controlled values.
Example: Controlled values that provide additional information about the subject
The following code fragment 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 clickable links as part of a user interface that implements a progressive disclosure strategy