The structured-content layer

The tagged-XML layer is built from a small vocabulary — <XMLTag>, <XMLElement>, the maps in Mapping.xml, and the backing <XMLStory> — spread across three parts of the package.

In short: This page is the format reference for IDML's tagged-XML layer. It documents the element vocabulary: <XMLTag> for tag names, <XMLElement> for the structure tree, <XMLAttribute> / <XMLComment> / <XMLInstruction> for the nodes inside it, <XMLStory> for the backing store of tagged-but-unplaced content, and <XMLExportMap> / <XMLImportMap> for the tag-to-style maps. The element and attribute names are facts drawn from the IDML vocabulary; the descriptions and the ordering are ours. The Paged renderer reads none of it — every construct here is Not yet parsed, so this page describes the format, not current behaviour.

This page is a format reference for the tagged-XML layer. Every element and attribute name below is a fact drawn from the IDML element vocabulary; the descriptions and the order are ours, arranged so the parts build on each other. None of it is read by the Paged renderer — every construct on this page is Not yet parsed, and the support column says so. To understand the parser behaviour behind that label, see why it's not parsed yet.

The layer spans three parts of the package:

<XMLTag> — the vocabulary (Tags.xml)

XML/Tags.xml lists the tags a document defines, one <XMLTag> per name. A tag is just a named, optionally coloured label; it carries no content of its own. Other parts of the layer refer to a tag by its Self id (conventionally of the form XMLTag/<name>).

<XMLTag> also carries a TagColor child element — the swatch shown beside the tag in the UI. Its value is either a UI-colour name (an InDesignUIColor enumeration value such as Yellow) or an explicit RGB triple. It is editorial chrome only and, like the rest of the tag, is not parsed.

Not yet parsedXMLTag/TagColor

<XMLElement> — the structure tree (BackingStory.xml)

The structure itself is a tree of <XMLElement> nodes. Each node names the tag it applies (MarkupTag) and may either point at content already placed in the layout or contain content directly. Nesting <XMLElement> inside <XMLElement> builds the document's XML hierarchy.

The two ways an <XMLElement> relates to content are worth keeping straight:

• It references placed content. When the tagged content already lives in the layout, the element sets XMLContent to that item's Self id — a Story, or a page item like Rectangle or TextFrame. The characters or the frame stay in their layout part; the element only labels them.
• It contains content. An <XMLElement> may directly hold child <XMLElement> nodes, <XMLAttribute>, <XMLComment>, and <XMLInstruction> nodes, plus <Content> (a run of text) and <Br> (a break) — and, for not-yet-placed material, the same page-item and style-range elements that can appear in a story.

<XMLAttribute>

XML attributes attached to a tagged element. A flat name/value pair.

<XMLComment>

An XML comment recorded inside the structure tree.

<XMLInstruction>

An XML processing instruction recorded inside the structure tree.

<XMLStory> — the backing store (BackingStory.xml)

XML/BackingStory.xml wraps the whole structure tree. Its root is the package's idPkg:BackingStory element (carrying a DOMVersion), and inside it is a single <XMLStory>.

An <XMLStory> is structurally identical to a layout Story: it can hold ParagraphStyleRange and CharacterStyleRange runs, Table elements, anchored frames, and everything else a story can — with <XMLElement> nodes interleaved to record the structure. Its job is twofold: to anchor the root of the XML tree, and to hold any content that has been tagged but not yet placed on a page. Once content is placed, the matching <XMLElement> points at the layout item by XMLContent instead.

Not yet parsedXML/BackingStory.xml as a whole — the root idPkg:BackingStory reference is dropped by the design-map parser.

<XMLExportMap> and <XMLImportMap> — the maps (Mapping.xml)

XML/Mapping.xml records how tags relate to InDesign styles, in two directions. <XMLExportMap> carries the style-to-tag mapping (which style becomes which tag on export); <XMLImportMap> carries the tag-to-style mapping (which tag becomes which style on import). Both refer to a tag by an XMLTag Self id and to a style by a ParagraphStyle or CharacterStyle Self id.

A note on these tables

The names and value domains above are facts: they are the element and attribute names IDML uses, and any code that reads or writes this layer must match them exactly. The support column, by contrast, describes the Paged renderer, and it reads the same all the way down — not yet parsed. There is no example to embed for this chapter, because there is no rendered output to validate against: the renderer produces identical pages whether or not these parts are present. The next page shows exactly where in the engine that boundary sits.

Frequently asked questions

What is the difference between an <XMLElement> and an <XMLTag>? An <XMLTag> in Tags.xml is just a named, optionally coloured label — the vocabulary. An <XMLElement> in BackingStory.xml is a node in the structure tree that applies a tag (via its MarkupTag reference) to some content. Many elements can use the same tag.

How does a tagged element connect to the text or frame it labels? Either by reference or by containment. When the content is already placed in the layout, the element sets XMLContent to that item's Self id (a Story, Rectangle, or TextFrame); when the content is tagged but not yet placed, the element holds it directly inside the backing <XMLStory>.

Does Paged read any of these elements or attributes? No. Every row in every table on this page is marked Not yet parsed, and the support column reads the same all the way down. The names are accurate IDML facts, but the renderer acts on none of them.

Why is there no example to embed for this chapter? Because there is no rendered output to validate an example against — the renderer produces identical pages whether or not these parts are present. Our examples are checked against the real renderer in CI, and a layer it does not parse has nothing to check.