Subject scheme maps
Subject scheme maps and their usage
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.
<topicmeta>
element to clarify the meaning of a value:- A
<navtitle>
(or a<titlealt>
element with a@title-role
ofnavigation
) 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.
- 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.
- 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.
- If an attribute specifies a value in the taxonomy, and a DITAVAL or other categorization tool is configured with that value, the rule matches.
- Otherwise, if the parent value in the taxonomy has a rule, that matches.
- 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>