Explainer
DITA XML Examples: Task, Map, Conref, Keyref
The Short Answer
DITA Is Plain XML in Three Kinds of File
DITA content is XML text files. A topic holds one unit of content and is typed: task, concept, or reference. A map lists topics and sets the publication's structure. Optional profiling files control conditions. Everything below uses DITA 1.3, the current approved OASIS Standard; DITA 2.0 is still in beta (see DITA 2.0 is coming).
This page is the worked example. For the definitions behind it, read DITA topic types and maps, keys, and conref; for the standard itself, the DITA standard page.
A Task Topic
Replacing an Air Filter
A task answers "how do I do it?" The file below is complete. The first lines are the XML declaration and the document type declaration, which names the DTD through its public identifier (-//OASIS//DTD DITA Task//EN). The identifier without a version number refers to the latest version of the DTD; a versioned form, -//OASIS//DTD DITA 1.3 Task//EN, pins DITA 1.3.
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">
<task id="replace-filter">
<title>Replacing the air filter</title>
<shortdesc>Swap a clogged air filter for a new one.</shortdesc>
<taskbody>
<prereq><p>Shut down the unit and let it cool.</p></prereq>
<steps>
<step>
<cmd>Open the <keyword keyref="product-name"/> access panel.</cmd>
<info><note conref="warnings.dita#warnings/hot-surface"/></info>
</step>
<step><cmd>Pull the old filter straight out.</cmd></step>
<step><cmd>Slide in the new filter with the arrow toward the fan.</cmd></step>
</steps>
<result><p>Airflow returns to the normal range.</p></result>
</taskbody>
</task>The structure is the point. <prereq> is what must be true first, <steps> holds the procedure, and every <step> must contain a <cmd>, the instruction itself. Supporting text goes in <info> and the outcome in <result>. Two elements here are references, not text: the <keyword keyref="product-name"/> and the <note conref="..."/>. Both are explained below.
Concept and Reference
The Other Two Everyday Topic Types
A concept explains what something is. It has a title and a body of ordinary paragraphs, lists, and figures, and no steps:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="air-filter">
<title>The air filter</title>
<conbody>
<p>The air filter removes particles from intake air before it
reaches the compressor. A clogged filter reduces airflow.</p>
</conbody>
</concept>A reference holds facts for quick lookup. Its body is built from tables, property lists, syntax sections, and generic sections, not from prose. Here a simple table carries a part number and interval (the values are invented for the example):
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd">
<reference id="filter-specs">
<title>Air filter specifications</title>
<refbody>
<simpletable>
<sthead>
<stentry>Model</stentry>
<stentry>Part number</stentry>
<stentry>Replace every</stentry>
</sthead>
<strow>
<stentry>Model 3000</stentry>
<stentry>AF-300</stentry>
<stentry>500 hours</stentry>
</strow>
</simpletable>
</refbody>
</reference>Keeping the three apart is what lets a build treat them differently, and lets a writer see at a glance what a missing topic should contain.
A Map
The Map Is the Publication
The topics above do not know they belong to a manual. The map does. Nesting <topicref> elements sets the hierarchy, and <keydef> defines a key without adding anything to the table of contents or the output:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
<map>
<title>Model 3000 Service Manual</title>
<keydef keys="product-name">
<topicmeta><keywords><keyword>Model 3000</keyword></keywords></topicmeta>
</keydef>
<topicref href="air-filter.dita">
<topicref href="replace-filter.dita"/>
<topicref href="filter-specs.dita"/>
</topicref>
</map>Here the key product-name is bound to the text "Model 3000". A second map for another product could bind the same key to different text and reuse the same topics unchanged.
Reuse
Conref and Keyref in the Same Task
Both references in the task resolve at build time. The keyref asks the map for the key product-name and gets "Model 3000". The conref points at an element in another file, in the form file#topic-id/element-id. The approved warning lives once, in its own topic:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="warnings">
<title>Approved warnings</title>
<conbody>
<note id="hot-surface" type="warning">Surfaces are hot after operation.</note>
</conbody>
</concept>Every task that references warnings.dita#warnings/hot-surface shows the same text, and changing the warning once changes it everywhere. Use a keyref when the value should vary by map or product, and a conref when the text must be identical wherever it appears. The full set of mechanisms, including conkeyref and conditions, is in the maps, keys, and conref guide.
Output
What the Build Does With Them
Publishing is a processor's job. With the DITA Open Toolkit you give it the map and a format:
dita --input=model-3000.ditamap --format=pdf
dita --input=model-3000.ditamap --format=html5The toolkit reads the map, finds the topics, resolves the key and the content reference, and then transforms the result into the chosen format. The reader sees one topic with the values filled in. The sketch below is plain text; real PDF or HTML layout depends on the stylesheet:
Replacing the air filter
Swap a clogged air filter for a new one.
Before you begin
Shut down the unit and let it cool.
1. Open the Model 3000 access panel.
Warning: Surfaces are hot after operation.
2. Pull the old filter straight out.
3. Slide in the new filter with the arrow toward the fan.
Result: Airflow returns to the normal range.How the toolkit works, and what its output formats are, is covered in the DITA Open Toolkit explained. For the PDF path in general, see how XML becomes a PDF.
Before You Copy It
When an Example Is Not a Content Model
These files are valid starting points, and a starter file is easy to get. What an example cannot tell you is which topic types your content needs, how finely to split it, and which text may be reused and which must not be. Those decisions are your content model, and copying a sample does not make one. We make the case in a template is not a content model. For validation, see DTD vs XSD; to build skills, see how to learn DITA.
FAQ
Questions We Hear
What is DITA XML?
XML written to the Darwin Information Typing Architecture, an OASIS standard for topic-based content. Topics (task, concept, reference) hold the content, and maps assemble topics into publications. A DITA file is plain XML that validates against the DITA DTDs or XML Schemas.
What does a DITA file look like, and what is the file format?
Topics and maps are XML text files, conventionally with the extensions .dita and .ditamap, and conditional processing profiles use .ditaval. Each starts with a root element (task, concept, reference, or map) and usually a DOCTYPE that names the DTD. The examples above are complete, small files of each kind.
Where is the DITA XML schema?
OASIS publishes the DITA 1.3 grammar as DTD and XML Schema packages alongside the specification. Which one you validate against is a tooling choice; our DTD vs XSD guide explains the trade-offs. The document type declaration in each example is what points an editor or processor at the DTD.
Is there a DITA template I can start from?
Yes, any DITA editor will give you a blank task, concept, or reference with the right DOCTYPE, like the ones on this page. A starter file is not the hard part, though. The decisions that matter are which topic types you use, how content is split, and what reuse is allowed, and those belong in an information model.
How do I turn DITA XML into a PDF?
Run the map through a DITA processor. The DITA Open Toolkit is the usual free one: you give it the map and an output format, it resolves keys, content references, and conditions, and it produces the PDF or HTML. Styling is controlled by a plug-in rather than the XML itself.
What is the difference between a conref and a keyref?
A conref copies an element's content from another element at build time, by direct address. A keyref points at a key, and the map decides what the key resolves to. In the examples, the warning is pulled in by conref; the product name is supplied by keyref.
Get In Touch
Turn Examples Into a Working Model
Tell us what you publish and where it has to go. We will help you decide how it should be structured before you author at scale.