subjectScheme

A subjectScheme is a specialized DITA map that defines a collection of controlled values rather than a collection of topics.

Default values in the scheme (specified by <defaultSubject>) apply only if the XML DTD / schema or instance doesn't specify a value in some other way. The precedence of the different methods of setting a value is:

An explicit value in the element instance
A default value in the DTD or XML Schema
Cascaded values within the document
Cascades from a higher level document to this document
A default controlled value for a scheme
Values in processing rules

Contains

Note: These models represent only the default document types distributed by OASIS. Actual content models will differ with each new document type.

Doctype	Content model
subjectScheme	( (title) (optional) then (topicmeta) (optional) then ( (anchor or data or data-about or enumerationdef or hasInstance or hasKind or hasNarrower or hasPart or hasRelated or navref or relatedSubjects or reltable or schemeref or subjectdef or subjectHead or subjectRelTable or topicref or (anchorref or keydef or mapref or topicgroup or topichead or topicset or topicsetref) ) (any number) ) )

Contained by

This element is not contained by any other elements.

Inheritance

- map/map subjectScheme/subjectScheme

Example

<subjectScheme>
  <!-- Pull in a scheme that defines unix OS values -->
  <schemeref href="unixOS.ditamap"/>
  <!-- Define new OS values that are merged with those in the unixOS scheme -->
  <subjectdef keys="os">
    <subjectdef keys="linux"/>
    <subjectdef keys="mswin"/>
    <subjectdef keys="zos"/>
  </subjectdef>
  <!-- Define application values -->
  <subjectdef keys="app" navtitle="Applications">
    <subjectdef keys="apacheserv" href="subject/apache.dita"/>
    <subjectdef keys="mysql"      href="subject/sql.dita"/>
  </subjectdef>

  <!-- Define an enumeration of the platform attribute, equal to
       each value in the OS subject. This makes the following values
       valid for the platform attribute: linux, mswin, zos -->
  <enumerationdef>
    <attributedef name="platform"/>
    <subjectdef keyref="os"/>
  </enumerationdef>
  <!-- Define an enumeration of the otherprops attribute, equal to
       each value in the application subjects.
       This makes the following values valid for the otherprops attribute:
       apacheserv, mysql -->
  <enumerationdef>
    <attributedef name="otherprops"/>
    <subjectdef keyref="app"/>
  </enumerationdef>
</subjectScheme>

Example: how hierarchies affect filtering

In the following sample, there are subcategories within the general "os" category.

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

The following values are valid on the platform attribute: linux, redhat, suse, mswin, zos. If any other values are encountered, processors validating against the scheme should give a warning. As a result, the values could be used in this way:

<p platform="linux">You must set up a cron job to ...</p>
<p platform="redhat">To set up the cron job, ...</p>

Processors should be aware of hierarchies of attributes defined in subject scheme maps, and process them differently than they might if the attributes were not defined in a hierarchy. Using the values "linux" and "redhat" from the scheme above, where the subject "linux" is a container for the subject "redhat", filtering and flagging operate as follows:

Table 1. How to evaluate subjects in a hierarchy
Behavior of "linux"	Behavior of "redhat"	How to evaluate platform="redhat"	How to evaluate platform="linux"
set to "exclude"	set to "exclude"	Excluded	Excluded
	set to "include" or "flag"	Excluded. This is an error condition, because if all linux content is excluded, redhat is also excluded. Applications may recover by generating an error message.	Excluded
	unspecified	Excluded, because "redhat" is a special kind of "linux", and linux is excluded.	Excluded
set to "include"	set to "exclude"	Excluded, because all redhat content is excluded	Included
	set to "include"	Included	Included
	set to "flag"	Included and flagged with the "redhat" flag	Included
	unspecified	Included, because all Linux content is included	Included
set to "flag"	set to "exclude"	Excluded, because all redhat content is excluded	Included and flagged with the "linux" flag
	set to "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
	set to "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	set to "exclude"	Excluded, because all redhat content is excluded	If the default for platform values is "include", this is included. If the default for platform values is "exclude", this is excluded.
	set to "include"	Included	Included, because all "redhat" content is included, and general Linux content also applies to RedHat
	set to "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 for platform values is "include", this is included. If the default for platform values is "exclude", this is excluded.	If the default for platform values is "include", this is included. If the default for platform values is "exclude", this is excluded.

Attributes