`<enumerationdef>`

An enumeration definition is a binding of an attribute to a set of controlled values. The set of controlled values can be limited to a specific element or it could be empty.

Usage information

An enumeration definition can accomplish the following goals:

Bind a set of controlled values to an attribute

When the <enumerationdef> element contains only an <attributedef> and a <subjectdef> element, the set of controlled values that are bound to the attribute apply to all elements. For example, when <enumerationdef> contains only <attributedef name="value"/>, the @value attribute is limited to the specified enumeration for all elements that can specify the @value attribute.

Limit a set of controlled values to a specific element and attribute pair

When the <enumerationdef> element contains an <attributedef>, a <subjectdef>, and an <elementdef> element, the enumeration applies to the specified attribute only on the specified element. The enumeration does not apply to the attribute on other elements.

For example, when the <enumerationdef> element contains both <attributedef name="type"/> and <elementdef name="note"/>, only the @type attribute on the <note> element is limited to the specified enumeration. The possible values for the @type attribute on other elements are not affected.

Specify the default value for an attribute or element and attribute pair

When the <enumerationdef> element contains a <defaultSubject> element, processors operate as if the value specified by the <defaultSubject> element is explicitly set in the DITA source and the XML grammar does not set a default value for the attribute.

For example, given the following <enumerationdef> element, if no value is set for the @audience attribute on <draft-comment> in the DITA source, processors operate as if the @audience attribute is explicitly set to spec-editors:

<subjectScheme>
  <!-- ... -->
  <enumerationdef>
    <elementdef name="draft-comment"/>
    <attributedef name="audience"/>
    <subjectdef keyref="values-audience-draft-comment"/>
    <defaultSubject keyref="spec-editors"/>
  </enumerationdef>
  <!-- ... -->
</subjectScheme>

Specify that an attribute is not valid.

When the <enumerationdef> element contains a @subjectdef element that does not reference a subject, no value is valid for the attribute.

For example, the following code sample specifies that no tokens are valid for the @props attribute:

<subjectScheme>
  <!-- ... -->
  <enumerationdef>
    <attributedef name="props"/>
    <subjectdef/>
  </enumerationdef>
  <!-- ... -->
</subjectScheme>

Specialization hierarchy

The <enumerationdef> element is specialized from <topicref>. It is defined in the subject scheme module.

Processing expectations

See Determining effective attribute values

Content model

<elementdef> ?, <attributedef> , <subjectdef> +, <defaultSubject> ?, <data> **

In order

Optional <elementdef>
<attributedef>
One or more <subjectdef>
Optional <defaultSubject>
Zero or more Zero or more <data>

Attributes

The following attributes are available on this element: ID and conref attributes, @base, @class, @outputclass, and @status.

@base

Specifies metadata about the element. It is often used as a base for specialized attributes that have a simple syntax for values, but which are not conditional processing attributes.

The @base attribute takes a space-delimited set of values. However, when serving as a container for generalized attributes, the attribute values will be more complex. See Attribute generalization for more details.

@class (not for use by authors)

This attribute is not for use by authors. If an editor displays @class attribute values, do not edit them. Specifies a default value that defines the specialization ancestry of the element. Its predefined values allow DITA tools to work correctly with specialized elements. In a generalized DITA document the @class attribute value in the generalized instance might differ from the default value for the @class attribute for the element as given in the DTD or schema. See The class attribute rules and syntax for more information. This attribute is specified on every element except for the <dita> container element. It is always specified with a default value, which varies for each element.

@conaction

Specifies how the element content will be pushed into a new location. The following values are valid:

mark: The element acts as a marker when pushing content before or after the target, to help ensure that the push action is valid. The element with conaction="mark" also specifies the target of the push action with @conref. Content inside of the element with conaction="mark" is not pushed to the new location.
pushafter: Content from this element is pushed after the location specified by @conref on the element with conaction="mark". The element with conaction="pushafter" is the first sibling element after the element with conaction="mark".
pushbefore: Content from this element is pushed before the location specified by @conref on the element with conaction="mark". The element with conaction="pushbefore" is the first sibling element before the element with conaction="mark".
pushreplace: Content from this element replaces any content from the element referenced by the @conref attribute. A second element with conaction="mark" is not used when using conaction="pushreplace".
-dita-use-conref-target: See Using the -dita-use-conref-target value for more information.

See Pushing reusable content to a new location for examples and details about the syntax.

@conkeyref

Specifies a key name or a key name with an element ID that acts as an indirect reference to reusable content. The referenced content is used in place of the content of the current element. See Indirect key-based content reuse for more details about the syntax and behaviors.

@conref

Specifies a URI that references a DITA element. The referenced content is used in place of the content of the current element. See Direct URI-based content reuse for examples and details about the syntax.

@conrefend

Specifies a URI that references the last element in a sequence of elements, with the first element of the sequence specified by @conref. The referenced sequence of elements is used in place of the content of the current element. See Reusing a range of elements for examples and details about the syntax.

@id

Specifies an identifier for the current element. This ID is the target for references by @href and @conref attributes and for external applications that refer to DITA or LwDITA content. This attribute is defined with the XML data type NMTOKEN, except where noted for specific elements within the language reference.

See id attribute for more details.

@outputclass

Specifies a role that the element is playing. The role must be consistent with the basic semantic and expectations for the element. In particular, the @outputclass attribute can be used for styling during output processing; HTML output will typically preserve @outputclass for CSS processing.

@status

Specifies the modification status of the element. The following values are valid: new, changed, deleted, unchanged, and -dita-use-conref-target.

Example

This section is non-normative.

The following code sample contains three enumeration definitions:

<subjectScheme>
    
    <!-- DEFINE SETS OF CONTROLLED VALUES -->

    <!-- 1. Values for @audience on <draft-comment> -->
    <subjectdef keys="values-audience-draft-comment">
        <subjectdef keys="spec-editors"/>
        <subjectdef keys="tc-reviewers"/>
    </subjectdef>
    
    <!-- 2. Values for @otherprops -->
    <subjectdef keys="values-otherprops">
        <subjectdef keys="examples"/>
    </subjectdef>
    
    <!-- BINDS SETS OF CONTROLLED VALUES -->

    <!-- 1. Binding for @audience on <draft-comment> -->
    <enumerationdef>
        <elementdef name="draft-comment"/>
        <attributedef name="audience"/>
        <subjectdef keyref="values-audience-draft-comment"/>
        <defaultSubject keyref="spec-editors"/>
    </enumerationdef>
    
    <!-- 2. Binding for @otherprops -->
    <enumerationdef>
        <attributedef name="otherprops"/>
        <subjectdef keyref="values-otherprops"/>
    </enumerationdef>

    <!-- 3. Binding for @props -->
    <enumerationdef>
        <attributedef name="props"/>
        <subjectdef/>
    </enumerationdef>

</subjectScheme>

The permissible values for the @audience attribute on the <draft-comment> element are restricted to the subject values-audience-draft-comment. This means that the only allowed values are spec-editors and tc-reviewers. If no value for @audience is specified for a <draft-comment> element in the DITA source, it is assumed to be set to spec-editors.
The permissible values for @otherprops are restricted to the subject values-otherprops. This means that the only valid value for @otherprops is examples.
The enumeration for the @props attribute contains a <subjectdef> element that does not reference a subject. That means that no values are valid for the @props attribute.