Working with maps

DITA maps collect and organize references to DITA topics to indicate the relationships among the topics. They can be used to identify the topics you want to include in a deliverable, and to create tables of contents and related links for the information.

Maps can organize topics into hierarchies, tables, and groups, and also have special elements for referencing other maps. You can use multiple maps to pull different deliverables out of the same set of topics, and to separate the concerns of managing deliverables and architecting information from the concerns of topic authoring.

The architectural specification describes DITA maps and relationship tables at

For a practical approach to setting up relationship tables, see

Controlling heading hierarchies using ditamaps 

People often ask what to do to make extra headings and levels of hierarchy appear within a table of contents. 

A common misconception is that if a map includes a submap, the title of the submap will appear as an extra heading in output. This does not occur.  Also, the topics within the submap appear at the same hierarchy level as other topics that are peer to the submap itself; being in a submap does not cause extra "indenting".

To add an extra heading to a map, a good method is to use a <topicref> element pointing to a topic that contains a title and nothing else. This method is easy to manage for translation.

Another method is to use the <topichead> element. This element did not appear in PDF output using previous versions of the DITA Open Toolkit. However, version 1.4 of the DITA Open Toolkit does create headings from <topichead>.


Tools for modeling maps

The Information Architecture Workbench (formerly IBM Task Modeler) enables you to analyze the organization of your content and creates a corresponding DITA map along with stub topics for to-be-developed topics in the map.

This tutorial provides a quick but comprehensive introduction to using the IAWB to analyze and create a complete map of a sample scenario: IAWB Handout by Ben Welman.


Editors for the Architecture area: Focus Areas: BPEL | DITA | ebXML | IDtrust | OpenDocument | SAML | UBL | UDDI
OASIS sites: OASIS | Cover Pages | | AMQP | CGM Open | eGov | Emergency | IDtrust | LegalXML | Open CSA | OSLC | WS-I