Subject scheme maps

Subject scheme maps can be used to define controlled values and subject definitions. The controlled values can be bound to attributes, as well as element and attribute pairs. The subject definitions can contain metadata and provide links to more detailed information; they can be used to classify content and provide semantics that can be used in taxonomies and ontologies.

A DITA map can reference a subject scheme map by using a <mapref> element. Processors also MAY provide parameters by which subject scheme maps are referenced.

Subject scheme maps

Subject scheme maps use key definitions to define collections of controlled values and subject definitions.

Controlled values are tokens that can be used as values for attributes. For example, the @audience attribute can take a value that identifies the users that are associated with a particular product. Typical values for a medical-equipment product might include therapist, oncologist, physicist, and radiologist. In a subject scheme map, an information architect can define a list of these values for the @audience attribute. An authoring tool can then provide a pick list for values for the attribute and generate a warning if an author attempts to specify a value that is not one of the controlled values. Controlled values can also be used to select content for filtering and flagging at build time.

Subject definitions are classifications and sub-classifications that compose a tree. Subject definitions provide semantics that can be used in conjunction with taxonomies and ontologies.

Key references to controlled values are resolved to a key definition using the same precedence rules as apply to any other key. However, once a key is resolved to a controlled value, that key reference does not typically result in links or generated text.

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.

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. If an enumeration specifies an empty <subjectdef> element that does not reference a set of controlled values, no value is valid for the attribute. An enumeration can also 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.

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

This section is non-normative.

The following code sample 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 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, as it merely identifies the parent or container subject.

Example: Binding an attribute to an empty set

This section is non-normative.

The following code sample specifies that there are no valid values for the @outputclass attribute:

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

Authors will not be able to specify the @outputclass attribute on an element.

Processing controlled attribute values

An enumeration of controlled values can be defined with hierarchical levels by nesting subject definitions. This affects how processors perform filtering and flagging.

The following behavior is expected of processors in regard to subject scheme maps:
  • Processors SHOULD be aware of the hierarchies of attribute values that are defined in subject scheme maps for purposes of filtering, flagging, or other metadata-based categorization.
  • Processors SHOULD validate that the values of attributes that are bound to controlled values contain only valid values from those sets. This requirement is needed because basic XML parsers do not validate the list of controlled values. If the controlled values are part of a named key scope, the scope name is ignored for the purpose of validating the controlled values.
  • Processors SHOULD check that all values listed for an attribute in a DITAVAL file are bound to the attribute by the subject scheme before filtering or flagging. If a processor encounters values that are not included in the subject scheme, it SHOULD issue a warning.
Processors SHOULD apply the following algorithm when they apply filtering and flagging rules to attribute values that are defined as a hierarchy of controlled values and bound to an enumeration:
  1. If an attribute specifies a value in the taxonomy, and a DITAVAL or other categorization tool is configured with that value, the rule matches.
  2. Otherwise, if the parent value in the taxonomy has a rule, that matches.
  3. Otherwise, continue up the chain in the taxonomy until a matching rule is found.

Example: A hierarchy of controlled values and conditional processing

This section is non-normative.

The following code sample shows a set of controlled values that contains a hierarchy.

<subjectScheme>
  <subjectdef keys="users">
    <subjectdef keys="therapist">
      <subjectdef keys="novice-therapist"/>
      <subjectdef keys="expert-therapist"/>
    </subjectdef>
    <subjectdef keys="oncologist"/>
    <subjectdef keys="physicist"/>
    <subjectdef keys="radiologist"/>
  </subjectdef>
  <enumerationdef>
    <attributedef name="audience"/>
    <subjectdef keyref="users"/>
  </enumerationdef>
</subjectScheme>

Processors that are aware of the hierarchy that is defined in the subject scheme map will handle filtering and flagging in the following ways:

  • If "therapist" is excluded, both "novice-therapist" and "expert-therapist" are by default excluded.
  • If "therapist" is flagged and "novice-therapist" is not explicitly flagged, processors automatically flag "novice-therapist" since it is a type of therapist.

The @subjectrefs attribute

The @subjectrefs attribute specifies one or more keys that are defined by a subject definition in a subject scheme map. Multiple values are separated by white space.

The @subjectrefs attribute cascades. When specified on a topic reference, the @subjectrefs attribute associates the referenced resource with subjects that are defined in subject scheme maps.

The DITA 2.0 specification does not indicate processing expectations for the @subjectrefs attribute. The DITA Technical Committee expects to specify such expectations in the future.

Examples of subject scheme maps

This section is non-normative.

This section contains examples and scenarios that illustrate the use of subject scheme maps.

Example: a subject scheme map used to define taxonomic subjects

This section is non-normative.

A subject scheme map can be used to define taxonomic subjects. Once defined, the subjects can be referenced by specifying a @subjectrefs attribute on a <topicref> element.

The following subject scheme map defines a set of subjects that are used to classify content:

<subjectScheme>
  <subjectdef keys="content-types">
    <subjectdef keys="conceptual-material"/>
    <subjectdef keys="reference"/>
    <subjectdef keys="tutorial"/>
  </subjectdef>
  <subjectdef keys="operating-systems">
    <subjectdef keys="linux"/>
    <subjectdef keys="macosx"/>
    <subjectdef keys="windows"/>
  </subjectdef>
  <subjectdef keys="user-tasks">
    <subjectdef keys="administering"/>
    <subjectdef keys="developing"/>
    <subjectdef keys="installing"/>
    <subjectdef keys="troubleshooting"/>
  </subjectdef>
</subjectScheme>

The keys assigned to the subject definitions can be referenced by specifying the @subjectrefs attribute on topic references in a navigation map:

<map>
<title>User assistance for the Acme Widget</title>
<!-- ... -->
<topicref keyref="install-overview" subjectrefs="installing">
  <topicref keyref="install-linux"/>
  <topicref keyref="install-macosx"/>
  <topicref keyref="install-windows"/>
  <topicref keyref="install-troubleshooting" subjectrefs="troubleshooting"/>
</topicref>
<!-- ... -->
</map>

Because the @subjectrefs attribute cascades, the effective value of the above markup is the same as the following markup:

<map>
<title>User assistance for the Acme Widget</title>
<!-- ... -->
<topicref keyref="install-overview" subjectrefs="installing">
  <topicref keyref="install-linux" subjectrefs="installing"/>
  <topicref keyref="install-macosx" subjectrefs="installing"/>
  <topicref keyref="install-windows" subjectrefs="installing"/>
  <topicref keyref="install-troubleshooting" subjectrefs="installing troubleshooting"/>
</topicref>
<!-- ... -->
</map>

Example: How hierarchies defined in a subject scheme map affect filtering

This section is non-normative.

This scenario demonstrates how a processor evaluates attribute values when it performs conditional processing for an attribute that is bound to a set of controlled values.

Example

This section is non-normative.

A company defines a subject category for "Operating system", with a key set to os. There are sub-categories for Linux, Windows, and z/OS, as well as specific Linux variants: Red Hat Linux and SuSE Linux. The company then binds the values that are enumerated in the "Operating system" category to the @platform attribute:

<subjectScheme>
    <subjectdef keys="os">
        <topicmeta>
            <navtitle>Operating systems</navtitle>
        </topicmeta>
        <subjectdef keys="linux">
            <topicmeta>
                <navtitle>Linux</navtitle>
            </topicmeta>
            <subjectdef keys="redhat">
                <topicmeta>
                    <navtitle>RedHat Linux</navtitle>
                </topicmeta>
            </subjectdef>
            <subjectdef keys="suse">
                <topicmeta>
                    <navtitle>SuSE Linux</navtitle>
                </topicmeta>
            </subjectdef>
        </subjectdef>
        <subjectdef keys="windows">
            <topicmeta>
                <navtitle>Windows</navtitle>
            </topicmeta>
        </subjectdef>
        <subjectdef keys="zos">
            <topicmeta>
                <navtitle>z/OS</navtitle>
            </topicmeta>
        </subjectdef>
    </subjectdef>
    <enumerationdef>
        <attributedef name="platform"/>
        <subjectdef keyref="os"/>
    </enumerationdef>
</subjectScheme>

The enumeration limits valid values for the @platform attribute to the following: linux, redhat, suse, windows, and zos. If any other values are encountered, processors validating against the scheme will issue a warning.

The following table illustrates how filtering and flagging operate when the above map is processed by a processor. The first two columns provide the values specified in the DITAVAL file. The third and fourth columns indicate the results of the filtering or flagging operation.

att="platform" val="linux" att="platform" val="redhat" How platform="redhat" is evaluated How platform="linux" is evaluated
action="exclude" action="exclude" Excluded. Excluded.
action="include" or action="flag" Excluded. This is an error condition, because if all linux content is excluded, redhat also is excluded. Applications can recover by generating an error message. Excluded.
Unspecified Excluded, because redhat is a kind of linux, and linux is excluded. Excluded.
action="include" action="exclude" Excluded, because all redhat content is excluded. Included.
action="include" Included. Included.
action="flag" Included and flagged with the redhat flag. Included.
Unspecified Included, because all linux content is included. Included.
action="flag" action="exclude" Excluded, because all redhat content is excluded. Included and flagged with the linux flag.
action="include" Included and flagged with the linux flag, because linux is flagged and redhat is a type of linux. Included and flagged with the linux flag.
action="flag" Included and flagged with the redhat flag, because a flag is available that is specifically for redhat. Included and flagged with the linux flag.
Unspecified Included and flagged with the linux flag, because linux is flagged and redhat is a type of linux Included and flagged with the linux flag.
Unspecified action="exclude" Excluded, because all redhat content is excluded If the default value for @platform set in the DITAVAL is "include", this is included. If the default value for @platform set in the DITAVAL is "exclude", this is excluded.
action="include" Included. Included, because all redhat content is included, and general Linux content also applies to RedHat
action="flag" Included and flagged with the redhat flag. Included, because all redhat content is included, and general Linux content also applies to RedHat
Unspecified If the default value for @platform set in the DITAVAL is "include", this is included. If the default value for @platform set in the DITAVAL is "exclude", this is excluded. If the default value for @platform set in the DITAVAL is "include", this is included. If the default value for @platform set in the DITAVAL is "exclude", this is excluded.

Example: Defining values for @deliveryTarget

This section is non-normative.

You can use a subject scheme map to define the values for the @deliveryTarget attribute. This filtering attribute is intended for use with a set of hierarchical, controlled values.

Example

This section is non-normative.

In this scenario, one department produces electronic publications (EPUB, EPUB2, EPUB3, Kindle, etc.) while another department produces traditional, print-focused output. Each department needs to exclude a certain category of content when they build documentation deliverables.

The following subject scheme map provides a set of values for the @deliveryTarget attribute that accommodates the needs of both departments.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE subjectScheme PUBLIC "-//OASIS//DTD DITA Subject Scheme Map//EN" "subjectScheme.dtd"> 
<subjectScheme>
  <subjectHead>
    <subjectHeadMeta>
      <navtitle>Example of values for the @deliveryTarget attribute</navtitle>
      <shortdesc>Provides a set of values for use with the
        @deliveryTarget conditional-processing attribute. This set of values is
        illustrative only; you can use any values with the @deliveryTarget 
        attribute.</shortdesc>      
    </subjectHeadMeta>
  </subjectHead>
  <subjectdef keys="deliveryTargetValues">
    <topicmeta><navtitle>Values for @deliveryTarget attributes</navtitle></topicmeta>
    <!-- A tree of related values -->
    <subjectdef keys="print">
      <topicmeta><navtitle>Print-primary deliverables</navtitle></topicmeta>
      <subjectdef keys="pdf">
        <topicmeta><navtitle>PDF</navtitle></topicmeta>
      </subjectdef>
      <subjectdef keys="css-print">
        <topicmeta><navtitle>CSS for print</navtitle></topicmeta>
      </subjectdef>
      <subjectdef keys="xsl-fo">
        <topicmeta><navtitle>XSL-FO</navtitle></topicmeta>
      </subjectdef>
      <subjectdef keys="afp">
        <topicmeta><navtitle>Advanced Function Printing</navtitle></topicmeta>
      </subjectdef>
      <subjectdef keys="ms-word">
        <topicmeta><navtitle>Microsoft Word</navtitle></topicmeta>
      </subjectdef>
      <subjectdef keys="indesign">
        <topicmeta><navtitle>Adobe InDesign</navtitle></topicmeta>
      </subjectdef>
      <subjectdef keys="open-office">
        <topicmeta><navtitle>Open Office</navtitle></topicmeta>
      </subjectdef>
    </subjectdef>
    <subjectdef keys="online">
      <topicmeta><navtitle>Online deliverables</navtitle></topicmeta>
      <subjectdef keys="html-based">
        <topicmeta><navtitle>HTML-based deliverables</navtitle></topicmeta>
        <subjectdef keys="html">
          <topicmeta><navtitle>HTML</navtitle></topicmeta>
          <subjectdef keys="html5">
            <topicmeta><navtitle>HTML5</navtitle></topicmeta>
          </subjectdef>
        </subjectdef>
        <subjectdef keys="help">
          <topicmeta><navtitle>Contextual help</navtitle></topicmeta>
          <subjectdef keys="htmlhelp">
            <topicmeta><navtitle>HTML Help</navtitle></topicmeta>
          </subjectdef>
          <subjectdef keys="webhelp">
            <topicmeta><navtitle>Web help</navtitle></topicmeta>
          </subjectdef>
          <subjectdef keys="javahelp">
            <topicmeta><navtitle>Java Help</navtitle></topicmeta>
          </subjectdef>
          <subjectdef keys="eclipseinfocenter">
            <topicmeta><navtitle>Eclipse InfoCenter</navtitle></topicmeta>
          </subjectdef>
        </subjectdef>
        <subjectdef keys="epub">
          <topicmeta><navtitle>EPUB</navtitle></topicmeta>
          <subjectdef keys="epub2">
            <topicmeta><navtitle>EPUB2</navtitle></topicmeta>
          </subjectdef>
          <subjectdef keys="epub3">
            <topicmeta><navtitle>EPUB3</navtitle></topicmeta>
          </subjectdef>
          <subjectdef keys="ibooks">
            <topicmeta><navtitle>iBooks</navtitle></topicmeta>
          </subjectdef>
          <subjectdef keys="nook">
            <topicmeta><navtitle>nook</navtitle></topicmeta>
          </subjectdef>
        </subjectdef>
        <subjectdef keys="kindle">
          <topicmeta><navtitle>Amazon Kindle</navtitle></topicmeta>
          <subjectdef keys="kindle8">
            <topicmeta><navtitle>Kindle Version 8</navtitle></topicmeta>
          </subjectdef>
        </subjectdef>
      </subjectdef>
    </subjectdef>
  </subjectdef>
  <enumerationdef>
    <attributedef name="deliveryTarget"/>
    <subjectdef   keyref="deliveryTargetValues"/>
  </enumerationdef>
</subjectScheme>