`<relcolspec>`

A column specification in a relationship table column that provides default attribute values for the references in that column of a relationship table.

Usage information

You can use the <relcolspec> element to set default values for the attributes of the topics that are referenced in the column. For example, when you set the @type attribute to concept, all <topicref> elements in the column that do not have a @type attribute specified are treated as concepts.

Adding a <topicref> element to the <relcolspec> element defines a relationship between the topics that are contained within the <relcolspec> element and the topics that are referenced in the column of the relationship table. Note that this does not define a relationship between two cells in the same column.

Rendering expectations

When a <title> element exists inside of the <relcolspec> element, the content of the <title> element is intended to be used as the label for the related links that are defined and generated by the column. If the <title> element is not present, the labels for the related links are generated in the following ways:

If the <relcolspec> element contains a <topicref> element that specifies a navigation title, that navigation title is used for the label.
If the <relcolspec> element contains a <topicref> element that does not specify a navigation title but does reference a DITA topic, the label is derived from the navigation title of the referenced topic or, lacking that, the title of the topic.
If no title is specified and no <topicref> is present in the <relcolspec>, a rendering tool might choose to generate a title for the links generated from that column.

Processing expectations

When values are specified for attributes of <relcell> or <relrow> elements, those values override those defined for <relcolspec> attributes. Values specified for attributes of <relcolspec> elements override those defined for the <reltable> element.

Content model

<title>?, <topicmeta>?, <topicref>*

Contained by

<relheader>

In order

Optional <title>
Optional <topicmeta>
Zero or more <topicref>

Contained by

<relheader>

Inheritance

- map/relcolspec

The <relcolspec> element is a base element type. It is defined in the map module.

Attributes

The following attributes are available on this element: universal attributes and common map attributes (without @keyscope or @collection-type), @type, @scope, and @format.

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

@cascade (common map attributes)

Specifies how metadata attributes cascade within a map. The specification defines the following values:

merge: Indicates that the metadata attributes cascade, and that the values of the metadata attributes are additive. This is the processing default for the @cascade attribute.
nomerge: Indicates that the metadata attributes cascade, but that they are not additive for <topicref> elements that specify a different value for a specific metadata attribute. If the cascading value for an attribute is already merged based on multiple ancestor elements, that merged value continues to cascade until a new value is encountered. That is, setting cascade="nomerge" does not undo merging that took place on ancestor elements.

Processors can also define custom, implementation-specific tokens for this attribute.

See Cascading of metadata attributes in a DITA map for more information about how this attribute interacts with metadata attributes.

@chunk (common map attributes)

Specifies how a processor should render a map or branch of a map. For example, it can be used to specify that individual topic documents should be rendered as a single document, or that a single document with multiple topics should be rendered as multiple documents.

The following values are valid:

combine: Instructs a processor to combine the referenced source documents for rendering purposes. This is intended for cases where a publishing process normally results in a single output artifact for each source XML document.
split: Instructs a processor to split each topic from the referenced source document into its own document for rendering purposes. This is intended for cases where a publishing process normally results in a single output artifact for each source XML document, regardless of how many DITA topics exist within each source document.

Processors can also define custom, implementation-specific tokens for this attribute.

For a detailed description of the @chunk attribute and its usage, see Chunking.

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

Draft comment: Kristen J Eberlein 28 September 2022

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

@collection-type: The @collection-type attribute specifies how the children of a <topicref> element relate to their parent and to each other. This attribute, which is set on the parent element, typically is used by processors to determine how to generate navigation links in the rendered topics. For example, a @collection-type value of "sequence" indicates that children of the specifying <topicref> element represent an ordered sequence of topics; processors might add numbers to the list of child topics or generate next/previous links for online presentation. This attribute is available in topics on the <linklist> and <linkpool> elements, where it has the same behavior. Where the @collection-type attribute is available on elements that cannot directly contain elements, the behavior of the attribute is undefined.

Draft comment: robander

TO RESOLVE 13 May 2026: Make sure nothing here conflicts, and add a link from this to the architectural section

Draft comment: Kristen J Eberlein 28 September 2022

In the definitions of the supported values, do we want to refer to "resources" instead of "topics"? Since we specify that @collection-type specifies "how topics or links relate to each other" ...

Draft comment: robander

TO RESOLVE 13 May 2026: Good point, no strong feeling, but we should be consistent here, we already use "topics", "child topics", "children", and "referenced topics". Maybe:

Start with "Specifies how child topic references or links within the current element relate to each other"? Since this applies to children and we only sort of say that in the definitions of the tokens
When describing the tokens, maybe use "referenced resources", as in "Indicates that the order of the referenced resources is not significant"

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

@keyscope (common map attributes)

Specifies that the element marks the boundaries of a key scope.

See The keyscope attribute for information on using this attribute.

Draft comment: Kristen J Eberlein 28 September 2022

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

@keyscope: Defines a new scope for key definition and resolution, and gives the scope one or more names. For more information about key scopes, see Indirect key-based addressing.

Draft comment: robander

TO RESOLVE 13 May 2026: Double check each to make sure the latest content is consistent, and remove the draft comment

But also … it might be a good idea to keep this draft comment (and others for the keys/keyref stuff) until after that section is fully reviewed, so that we have an easy way to find these "content should be consistent" issues

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

Draft comment: robander Dec 28 2021

The text below matches 1.3 spec text but I'm nervous about "cannot link" type definition. It's describing how to generate links based on the current context in the map - it's not describing what the topic itself is allowed to link to, which is how I interpret "can".

Draft comment: robander

TO RESOLVE 13 May 2026: Yeah we should remove the can/cannot and replace with a description of the intent here... like, targetonly "The topic or resource can be the target of any context based linking, but is not meant to be updated with links related to this context."

similarly, none could be "The topic or resource does not participate in any context-based linking"

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.

Draft comment: Kristen J Eberlein 28 September 2022

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

@linking

By default, the relationships between the topics that are referenced in a map are reciprocal:

Child topics link to parent topics and vice versa.
Next and previous topics in a sequence link to each other.
Topics in a family link to their sibling topics.
Topics referenced in the table cells of the same row in a relationship table link to each other. A topic referenced within a table cell does not (by default) link to other topics referenced in the same table cell.

This behavior can be modified by using the @linking attribute, which enables an author or information architect to specify how a topic participates in a relationship. The following values are valid:

linking="none": Specifies that the topic does not exist in the map for the purposes of calculating links.
linking="sourceonly": Specifies that the topic will link to its related topics but not vice versa.
linking="targetonly": Specifies that the related topics will link to it but not vice versa.
linking="normal": Default value. It specifies that linking will be reciprocal (the topic will link to related topics, and they will link back to it).

Authors also can create links directly in a topic by using the <xref> or <link> elements, but in most cases map-based linking is preferable, because links in topics create dependencies between topics that can hinder reuse.

Note that while the relationships between the topics that are referenced in a map are reciprocal, the relationships merely imply reciprocal links in generated output that includes links. The rendered navigation links are a function of the presentation style that is determined by the processor.

Draft comment: robander

TO RESOLVE 13 May 2026: Ensure there is nothing conflicting, and add a link from here to the more architectural info that gives all the details

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

@search (common map attributes)

Specifies whether the target is available for searching. 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, no, and -dita-use-conref-target.

Draft comment: Kristen J Eberlein 28 September 2022

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

@search: Specifies whether the topic is included in search indexes.

Draft comment: robander

TO RESOLVE 13 May 2026: Update to use the same description, these are very similar but not exact. If the description is this short and similar it should be reused with conref.

@subjectrefs (common map attributes)

Specifies one or more keys that are each defined by a subject definition in a subject scheme map. Multiple values are separated by white space.

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

Examples

This section is non-normative.

The following section contains examples of how the <relcolspec> element can be used.

Example 1. Enforcing concept, type, and reference types with <relcolspec>

The following code sample shows how a <relcolspec> element can be used to define the types of topics that are referenced in a column. Three cells are defined within one row. The first cell contains one concept topic: puffins.dita. The second cell contains two task topics: puffinFeeding.dita and puffinCleaning.dita. The third cell contains a reference topic: puffinHistory.dita. Setting the @type on each column allows (but does not require) processors to validate that the topics in each column are of the expected type.

<map>
 <reltable>
  <relheader>
   <relcolspec type="concept"/>
   <relcolspec type="task"/>
   <relcolspec type="reference"/>
  </relheader>
  <relrow>
   <relcell><topicref href="puffins.dita"/></relcell>
   <relcell>
     <topicref href="puffinFeeding.dita"/>
     <topicref href="puffinCleaning.dita"/>
   </relcell>
   <relcell>
     <topicref href="puffinHistory.dita"/>
   </relcell>
  </relrow>
 </reltable>
</map>

Example 2. Relationship table column headers with topics and titles

The following code sample shows how topics and titles can be specified in a column header for relationship table column header:

<reltable>
  <relheader>
    <relcolspec type="task">
      <topicref href="tbs.dita">
        <topicmeta><navtitle>Troubleshooting</navtitle></topicmeta>
      </topicref>
    </relcolspec>
    <relcolspec type="reference">
      <topicref href="msg.dita">
        <topicmeta><navtitle>Messages</navtitle></topicmeta>
      </topicref>
    </relcolspec>
  </relheader>
  <relrow>
    <relcell>
      <topicref href="debug_login.dita">
        <topicmeta><linktitle>Debugging login errors</linktitle></topicmeta>
      </topicref>
    </relcell>
    <relcell>
      <topicref href="login_error_1.dita">
        <topicmeta><linktitle>Login not found</linktitle></topicmeta>
      </topicref>
    </relcell>
  </relrow>
  <relrow>
    <relcell>
      <topicref href="checking_access.dita">
        <topicmeta><linktitle>Checking access controls</linktitle></topicmeta>
      </topicref>
    </relcell>
    <relcell>
      <topicref href="login_error_2.dita">
        <topicmeta><linktitle>Login not allowed</linktitle></topicmeta>
      </topicref>
    </relcell>
  </relrow>
</reltable>

In addition to the relationships defined by the rows in the relationship table, the following relationships are now defined by the columns in the relationship table:

tbs.dita <–> debug_login.dita
tbs.dita <–> checking_access.dita
msg.dita <–> login_error_1.dita
msg.dita <–> login_error_2.dita

Ignoring the headers for a moment, the <reltable> here would ordinarily define a two-way relationship between debug_login.dita and login_error1.dita. This typically will be expressed as a link from each to the other. An application might render the link with a language-appropriate heading such as "Related reference", indicating that the target of the link is a reference topic.

The headers change this by specifying a new title. In the second column, the <topicref> specifies a title of "Messages", which should now be used together with the link to anything in that column. So, a generated link from debug_login.dita to login_error1.dita should be rendered together with the title of "Messages". How this is rendered together with the link is up to the application.