The layer model

A layer is defined once in the design map; a page item joins it by naming its id through ItemLayer.

In short: Layers are declared document-wide as <Layer> children of the Document element in designmap.xml, each carrying an id, a name, and three boolean switches — Visible, Printable, and Locked. A page item joins a layer by setting its ItemLayer attribute to that layer's Self id, so the link always points from the item to the layer and never the reverse. The order layers appear in the design map also fixes cross-layer paint order, while XML order only breaks ties between items on the same layer. This page is the attribute reference for both ends of that link and how the parser reads each one.

Layers are defined once, document-wide, as <Layer> children of the Document element in designmap.xml. Each definition is small — an id, a name, and three boolean switches — and a page item joins a layer by naming it. This page is the attribute reference for both ends of that link.

The <Layer> element

The parser collects every <Layer> it finds under Document into an ordered list. A <Layer> with no Self id is ignored — the id is the handle every ItemLayer resolves against, so a layer with nothing to be named by carries no information. The three booleans each have a default the parser applies when the attribute is absent, chosen to match how an unspecified layer behaves in InDesign: a layer is on, unlocked, and printing unless it says otherwise.

The list order is meaningful. The renderer keys cross-layer paint order off each layer's position in this list, so two items that live on different layers are stacked by their layers rather than by the order they appear in the spread XML — the XML order only breaks ties between items on the same layer. (The exact top-vs-bottom direction of that key is an internal detail; what a reader needs is that layer membership, not XML order, decides which of two cross-layer items wins the overlap.)

The ItemLayer back-reference

A layer holds no list of its members. Instead, each page item in a spread — Rectangle, Oval, Polygon, GraphicLine, TextFrame, or a Group — may carry an ItemLayer attribute whose value is the Self id of the layer it belongs to. The link points from the item to the layer, never the other way.

When an item's ItemLayer is missing — or names a layer that does not exist in the design map — the renderer does not suppress the item. It falls back to treating the item as visible and unlocked, which is the safe default: a missing or dangling reference should never silently make content disappear.

Seeing the link work

The package below defines two layers in its design map — a Front layer with Visible="true" and a Back layer with Visible="false" — and places two filled rectangles in the spread, each naming one layer through ItemLayer. Both rectangles are perfectly valid and both parse, but only the one on the visible layer reaches the page. The hidden layer's rectangle is dropped before it can paint.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<?aid style="50" type="document" readerVersion="6.0" featureSet="257" product="20.0(32)"?>
<Document xmlns:idPkg="http://ns.adobe.com/AdobeInDesign/idml/1.0/packaging" DOMVersion="20.0" Self="d" StoryList="ustory" Name="layer-visibility.indd" CMYKProfile="Coated FOGRA39 (ISO 12647-2:2004)" RGBProfile="sRGB IEC61966-2.1" SolidColorIntent="UseColorSettings" AfterBlendingIntent="UseColorSettings" DefaultImageIntent="UseColorSettings">
  <Layer Self="ulayer-front" Name="Front" Visible="true" Locked="false" Printable="true"/>
  <Layer Self="ulayer-back" Name="Back" Visible="false" Locked="false" Printable="true"/>
  <idPkg:Graphic src="Resources/Graphic.xml"/>
  <idPkg:Fonts src="Resources/Fonts.xml"/>
  <idPkg:Styles src="Resources/Styles.xml"/>
  <idPkg:Preferences src="Resources/Preferences.xml"/>
  <idPkg:Tags src="XML/Tags.xml"/>
  <idPkg:MasterSpread src="MasterSpreads/MasterSpread_umaster.xml"/>
  <idPkg:Spread src="Spreads/Spread_uspread.xml"/>
  <idPkg:Story src="Stories/Story_ustory.xml"/>
  <idPkg:BackingStory src="XML/BackingStory.xml"/>
</Document>

The numbers tell the story plainly. The spread holds two rectangles, so the package parses two page items. But the rendered page reports a single frame and a single paint command — the blue rectangle on the hidden Back layer never becomes output. That gap between what the document declares and what the page draws is the whole subject of visibility and printing.

Frequently asked questions

How does a page item get assigned to a layer in IDML? A page item joins a layer by setting its ItemLayer attribute to the Self id of a <Layer> defined in the design map. The reference runs from the item to the layer; a layer never holds a list of its members.

Which page items can carry an ItemLayer attribute? Any spread page item — a Rectangle, Oval, Polygon, GraphicLine, TextFrame, or a Group. Each may name the layer it belongs to through ItemLayer.

What happens if ItemLayer is missing or names a layer that does not exist? The renderer treats the item as being on the default layer — visible and unlocked — and draws it. A missing or dangling reference never makes content disappear, because the parser only suppresses an item when ItemLayer resolves to a real layer that is explicitly turned off.

Does the order of <Layer> elements matter? Yes. The parser keeps the layers in an ordered list, and the renderer keys cross-layer paint order off each layer's position in it. So when two items live on different layers, their layers decide which one wins the overlap; XML order only breaks ties between items on the same layer.