Glossary · Maps and linking

DITA relationship table

Also known as: reltable, relationship table

In DITA, a relationship table (<reltable>) is a map element that defines links between topics in the form of a table: topics in different cells of the same row are related, and processors generate links between them in the output.

DITA
Maps and linking

In one sentence

A DITA relationship table defines links between topics in a map: topics in different cells of the same row link to each other.

Example

A row relating the concept “How the air filter works”, the task “Replacing the air filter” and the reference “Filter specifications”, so each links to the other two in the output.

How it applies

Technical documentation: Relationship tables keep links out of the topics. A topic stays reusable because it does not hard-code links to topics that may not exist in another deliverable; the map decides which links are generated.
How it works: A <reltable> has a header (<relheader>) with one <relcolspec> per column — typically concept, task and reference — and rows (<relrow>) of cells (<relcell>). Topics in different cells of the same row are linked to each other; topics in the same cell are not, unless the cell's @collection-type is set to family.
Link direction: The @linking attribute controls whether a topic is a source of links, a target only, both or neither.
AI and retrieval: Relationship tables are explicit, typed relationships between topics — a small knowledge graph. They can be exported as links between chunks so that a retrieval system can follow “see also” relationships to the concept behind a task.

Relationship table vs. inline links

An inline <xref> is written into the topic text and travels with the topic everywhere. A relationship-table link exists only in the map where the table is defined.

In DITA markup

<reltable>
  <relheader>
    <relcolspec type="concept"/><relcolspec type="task"/><relcolspec type="reference"/>
  </relheader>
  <relrow>
    <relcell><topicref href="filter-basics.dita"/></relcell>
    <relcell><topicref href="replace-filter.dita"/></relcell>
    <relcell><topicref href="filter-specs.dita"/></relcell>
  </relrow>
</reltable>