Binding controlled values to an attribute

The controlled values defined in a subject scheme map can be bound to an attribute or an element and attribute pair. This affects the expected behavior for processors and authoring tools.

The <enumerationdef> element binds the set of controlled values to an attribute. Valid attribute values are those that are defined in the set of controlled values; invalid attribute values are those that are not defined in the set of controlled values. An enumeration can specify an empty <subjectdef> element. In that case, no value is valid for the attribute. An enumeration also can specify an optional default value by using the <defaultSubject> element.

If an enumeration is bound, processors SHOULD validate attribute values against the controlled values that are defined in the subject scheme map. For authoring tools, this validation prevents users from entering misspelled or undefined values. Recovery from validation errors is implementation specific.

The default attribute values that are specified in a subject scheme map apply only if a value is not otherwise specified in the DITA source or as a default value by the XML grammar.

To determine the effective value for a DITA attribute, processors check for the following in the order outlined:

  1. An explicit value in the element instance
  2. A default value in the XML grammar
  3. Cascaded value within the document
  4. Cascaded value from a higher level document to the document
  5. A default controlled value, as specified in the <defaultSubject> element
  6. A value set by processing rules

Example: Binding a list of controlled values to the @audience attribute

The following example illustrates the use of the <subjectdef> element to define controlled values for types of users. It also binds the controlled values to the @audience attribute:

<subjectScheme>
  <!-- Define types of users -->
  <subjectdef keys="users">
    <subjectdef keys="therapist"/>
    <subjectdef keys="oncologist"/>
    <subjectdef keys="physicist"/>
    <subjectdef keys="radiologist"/>
  </subjectdef>

  <!-- Bind the "users" subject to the @audience attribute.
       This restricts the @audience attribute to the following
       values: therapist, oncologist, physicist, radiologist -->
  <enumerationdef>
    <attributedef name="audience"/>
    <subjectdef keyref="users"/>
  </enumerationdef>
</subjectScheme>

When the above subject scheme map is used, the only valid values for the @audience attribute are "therapist", "oncologist", "physicist", and "radiologist". Note that "users" is not a valid value for the @audience attribute; it merely identifies the parent or container subject.

Example: Binding an attribute to an empty set

The following code fragment declares that there are no valid values for the @outputclass attribute.

<subjectScheme>
  <enumerationdef>
    <attributedef name="outputclass"/>
    <subjectdef/>
  </enumerationdef>
</subjectScheme>