`<subjectdef>`

The <subjectdef> element defines a subject. A subject can be used to define a controlled value or a taxonomic classification.

Usage information

The <subjectdef> element can use a <navtitle> element to supply a label for the subject. The @href attribute on <subjectdef> can be used to reference a topic that provides more information about a subject and how authors should use it when classifying content or specifying a value for an attribute.

Specialization hierarchy

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

Content model

<topicmeta> ?, ( <data> | <subjectdef> | <subjectHead> | <topicref> )*

In order

Optional <topicmeta>
Zero or more

Attributes

The following attributes are available on this element: link-relationship attributes, universal attributes, @collection-type, @impose-role, @keyref, @keys, @linking, @processing-role, and @toc.

For this element, the @impose-role attribute has a fixed value of keeptarget.

The following attributes are available on this element: universal attributes and the attributes defined below.

@collection-type (common map attributes)

Specifies how topics or links relate to each other. The processing default is unordered, although no default is specified in the OASIS-provided grammar files. The following values are valid:

unordered: Indicates that the order of the child topics is not significant.
sequence: Indicates that the order of the child topics is significant. Output processors will typically link between them in order.
choice: Indicates that one of the children should be selected.
family: Indicates a tight grouping in which each of the referenced topics not only relates to the current topic but also relate to each other.

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

@impose-role

Specifies whether this element will impose its role on elements in a referenced map. The attribute is ignored if the target of the reference is not a map or branch of a map. The following values are valid:

keeptarget: The role of the current reference is not imposed on the target of the reference. This is the default for the unspecialized <topicref> element and for many convenience elements such as <keydef>.
impose: The role of the current reference is imposed on the target of the reference. For example, if a specialized topic reference <chapter> uses this value and references a map, a topic reference that resolves in place of the <chapter> will be treated as if it were a chapter.
-dita-use-conref-target: See Using the -dita-use-conref-target value for more information.

See The href attribute for detailed information on supported values and processing implications.

For this element, the @impose-role attribute has a fixed value of keeptarget.

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

@keys

Specifies one or more names for a resource. See Setting key names with the keys attribute for information on using this attribute.

@linking (common map attributes)

Specifies linking characteristics of a topic specific to the location of this reference in a map. If the value is not specified locally, the value might cascade from another element in the map (for cascade rules, see Cascading of metadata attributes in a DITA map). The following values are valid:

targetonly: A topic can only be linked to and cannot link to other topics.
sourceonly: A topic cannot be linked to but can link to other topics.
normal: A topic can be linked to and can link to other topics. Use this to override the linking value of a parent topic.
none: A topic cannot be linked to or link to other topics.
-dita-use-conref-target: See Using the -dita-use-conref-target value for more information.

@processing-role (common map attributes)

Specifies whether the referenced resource is processed normally or treated as a resource that is only included in order to resolve references, such as key or content references. The following values are valid:

normal: Indicates that the resource is a readable part of the information set. It is included in navigation and search results. This is the default value for the <topicref> element.
resource-only: Indicates that the resource should be used only for processing purposes. It is not included in navigation or search results, nor is it rendered as a topic. This is the default value for the <keydef> element.

-dita-use-conref-target: See Using the -dita-use-conref-target value for more information.

If no value is specified but the attribute is specified on a containing element within a map or within the related-links section, the value cascades from the closest containing element.

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

@toc (common map attributes)

Specifies whether a topic appears in the table of contents (TOC) based on the current map context. If the value is not specified locally, the value might cascade from another element in the map (for cascade rules, see Cascading of metadata attributes in a DITA map). The following values are valid:

yes: The topic appears in a generated TOC.
no: The topic does not appear in a generated TOC.
-dita-use-conref-target: See Using the -dita-use-conref-target value for more information.

@type (link-relationship attributes)

Describes the target of a reference. See The type attribute for detailed information on supported values and processing implications.

Examples

This section is non-normative.

This section contains examples of how <subjectdef> elements can be used.

Example 1. Example of defining a set of controlled values

The following code sample shows how <subjectdef> elements can be used to define a set of controlled values:

<subjectdef keys="values-product">
    <subjectdef keys="free"/>
    <subjectdef keys="premium"/>
</subjectdef>

When this set of controlled values is bound to an attribute, the only valid values for the attribute are free and premium.

Example 2. Example of defining a simple taxonomy

The following code sample shows how <subjectdef> elements can be used to define a simple taxonomy of recreational hobbies:

<subjectdef keys="hobbies">
    <subjectdef keys="fiber-arts">
        <subjectdef keys="knitting"/>
        <subjectdef keys="quilting"/>
        <subjectdef keys="sewing"/>
    </subjectdef>
    <subjectdef keys="woodworking">
        <subjectdef keys="scroll-sawing"/>
        <subjectdef keys="whittling"/>
        <subjectdef keys="wood-turning"/>
    </subjectdef>
</subjectdef>

The taxonomy might be used to classify DITA topics or maps.