`<defaultSubject>`

The <defaultSubject> element specifies the default value for the attribute in cases where no value is specified. The default value must be one of the controlled values that are bound to the attribute.

Processing expectations

Draft comment: Kristen J Eberlein 03 December 2021

Do we want to make a normative statement about how processors should handle default values for attributes when they are specified by <defaultSubject>?

Draft comment: robander

TO RESOLVE 13 May 2026: I think this would be covered by the "how to determine attributes" topic, and does not need an extra rule here

Draft comment: Kristen J Eberlein 13 December 2021

Comments from review D:

Frank Wegmann: Let's assume, in the DTD or a specialization there is an attribute defined with an enumeration data type and some default value. Now a subject scheme imposes maybe different controlled values for that attribute with a different default value? How is an implementation supposed to validate a document instance? My naive understanding would be that the DTD/schema definitions have precedence. This would mean that if the subject scheme defines a set of controlled values none of which are in the attribute definition of the schema, then the default value of the DTD would be taken. But what is a tool like Oxygen supposed to be doing then? Maybe I ask this, because I have (apparently) no idea what's going on behind the scenes, but then I wonder if this is worth discussing in the spec? Not necessarily here, but earlier in the usage chapter.

Robert Anderson: I think we should add this as a draft comment in this page, and then make sure it is covered in the section about how to determine values: https://github.com/oasis-tcs/dita/blob/DITA-2.0/specification/archSpec/base/determining-effective-attribute-values.dita

I think the answer is implied by the language today, but it's not directly addressed. The spec says that if your scheme tells you "a" and "b" are the only valid values in an attribute, then specifying "x" and "y" are both in error, and processors / applications can treat that as an error. If you set up that scheme but your grammar files only allow "x" and "y", then you've set up a scheme that means every usage of that element is automatically an error condition.

Draft comment: robander

TO RESOLVE 13 May 2026: That referenced topic is the one we are stuck on, but that is where the rules for this should be specified. I think this section could / should be updated with a link to that section, because it's highly relevant when reading about this topic.

Specialization hierarchy

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

Content model

<data>**

Contained by

<enumerationdef>

Zero or more Zero or more <data>

Contained by

<enumerationdef>

Inheritance

- map/topicref subjectScheme/defaultSubject

The <defaultSubject> element is specialized from <topicref>. It is defined in the subjectScheme module.

Attributes

The following attributes are available on this element: link-relationship attributes, universal attributes, @impose-role, @keyref, @keys, @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.

@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 Referencing a key with the keyref attribute for information on using this attribute.

Draft comment: robander

The definiton above for @keyref should be synchronized with the definition in the linked section on keys.

Draft comment: robander

TO RESOLVE 13 May 2026: Check the topic we link to and make sure this is consistent, then remove the draft comment

@keys

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

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

Draft comment: Kristen J Eberlein 28 September 2022

Here is the content from the "DITA map attributes" topic:

@toc: Specifies whether topics are excluded from navigation output, such as a Web site map or an online table of contents. By default, <topicref> hierarchies are included in navigation output; relationship tables are excluded.

Draft comment: robander

TO RESOLVE 13 May 2026: I read that and kind of hate "web site map". Kind of think we should delete that bit from the other topic, and replace the first sentence there with a reused sentence from here.

@type (link-relationship attributes)

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

Example

This section is non-normative.

The following code sample limits the values for @platform to the os subject and sets the default value to linux:

<subjectScheme>
  <subjectdef keys="os">
    <subjectdef keys="linux"/>
    <subjectdef keys="mswin"/>
    <subjectdef keys="zos"/>
    <subjectdef keys="macos"/>
  </subjectdef>
  <enumerationdef>
    <attributedef name="platform"/>
    <subjectdef keyref="os"/>
    <defaultSubject keyref="linux"/>
  </enumerationdef>
</subjectScheme>

The result is that only the following values are permitted for @platform:

linux
macos
mswin
zos

If no value is specified for the @platform attribute in the DITA source, the value is assumed to be linux.