The friendly guide to the scope, format, and type attributes in DITA

In testing one day, I was running a set of sample content through the DITA-OT, and much to my consternation, the build was succeeding, but generating no content. The error log helped to ferret out the source of the problem; the preprocessor was attempting to extract a linktext and navtitle from an image file that could not be found.

The image in question was a keyref pulled in from a map referenced in the main map file. Everything validated, previews showed the images resolving correctly, yet the images steadfastly refused to be pulled in during preprocessing—so what was wrong?

The issue lay in the keydef itself:

keydef keys="test_image" href="media/image.png" type="png"

At a glance, this looks fine, but this keydef needs the format attribute, not the type attribute.

In working with clients who are new to DITA, we have noticed that the format attribute and its similar siblings, type and scope, can cause a great deal of confusion.

Scope

The scope attribute tells the processor when to validate the associated object based on its relationship to the current map. The default value is ‘local.’ The values it can take are:

• local: This object is part of my dataset, so validate it at runtime.
• peer: This object is not part of my dataset, but is maintained by another group, so don’t validate it
• external: This object is not part of my dataset, so I can’t validate it.

Format

The format attribute tells the processor how to validate the associated object. The default value is ‘dita.’ Typical values include ‘dita,’ html,’ ‘pdf,’ and ‘ditamap,’ but a good guideline is to have it match the file extension of the referenced object, like this:

<keydef keys="test_image" href="content/test_image.svg" format="svg"/>

Here, the processor will see that the referenced file is an svg, and attempt to validate it as such. In the anecdote earlier, since the format attribute was not explicitly declared, the processor attempted to validate the referenced svg as if it were a DITA file, causing a cascade of validation errors that led to no content being output.

Type

In the context of linking elements, the type attribute tells the processor what kind of object you’re referencing. The default value is the value of the closest ancestor or, failing that, topic. You generally set it to either the element type being referenced (table, fig, note) or the topic type (task, reference), like this:

<xref href="topics/duck_species.dita#ducks/mallard" type="fig"/>

Here, the processor will see that you’re referencing a figure, then perform any additional processing dictated by the transform. You can also supply an arbitrary value and use that when you process the content to create output.

Putting it all together

Taken together, these attributes describe how linked content is related to your current content, what is being linked, and how it will be presented to the user.

<xref href="http://youtu.be/MZjAantupsA" scope="external" format="html" type="media_video">Classic Music</xref>

Understanding what these attributes represent, how they are evaluated, and how they function when you don’t explicitly declare them is key to writing content that not only works, but works the way you want it to.