Drawio Syntax Metadata

Draw.io Syntax: Metadata

Purpose

This skill teaches how to build multi-page Draw.io diagrams, manage layers, attach custom properties via ` wrappers, define file-level variables, use the %placeholder% substitution system, add tooltips and links, and enable MathJax/LaTeX rendering. It covers everything OUTSIDE the individual cell creation covered by drawio-syntax-cells`.

Critical Rules (Memorize These)

1. ALWAYS use unique id values on every `` element. Duplicate diagram IDs corrupt the file.
2. **NEVER nest ` elements inside each other.** Every is a direct child of `.
3. **ALWAYS set placeholders="1" on the ` wrapper** to enable %variable%` substitution. Without it, placeholder tokens render as literal text.
4. ALWAYS use single-quoted JSON for the vars attribute on `: vars='{"key":"value"}'`. Double quotes around the attribute value break XML parsing.
5. NEVER omit the structural cells (id="0" and id="1" parent="0") on ANY page. Every `` MUST contain both.
6. ALWAYS keep cell IDs unique across ALL pages in the file, not just within a single page.
7. ALWAYS use the full `` wrapper when the diagram needs multi-page support, file-level variables, or MathJax.
8. **NEVER put id or value on the inner `** when using an wrapper. These attributes belong on `.

Decision Tree: When Do I Need This Skill?

Does the diagram need multiple pages/tabs?
  YES --> Section 1 (Multi-Page Diagrams)
Does the diagram need layers (background, foreground, annotations)?
  YES --> Section 2 (Layer System)
Does any cell need custom key-value metadata?
  YES --> Section 3 (Custom Properties)
Does the diagram need shared variables across all pages?
  YES --> Section 4 (File-Level Variables)
Does any label contain %placeholder% tokens?
  YES --> Section 5 (Placeholder System)
Does any cell need a tooltip or hyperlink?
  YES --> Section 6 (Tooltips and Links)
Does the diagram contain mathematical formulas?
  YES --> Section 7 (MathJax/LaTeX)

---

1. Multi-Page Diagrams

A multi-page diagram uses the full ` wrapper with multiple children. Each ` represents one tab/page in the Draw.io editor.

Structure

Rules

| Rule | Enforcement | |------|-------------| | Each ` has a unique id | ALWAYS — duplicate IDs corrupt the file | | Each has a name attribute | ALWAYS — this is the tab label | | Each page has its own and | ALWAYS — pages are independent | | Each contains id="0" and id="1" parent="0" | ALWAYS — mandatory structural cells | | Cell IDs are unique across ALL pages | ALWAYS — NEVER reuse an ID from another page | | elements are siblings, not nested | ALWAYS — NEVER nest a diagram inside another | | compressed="false" on ` | ALWAYS for AI-generated XML |

Internal Page Links

Link from one cell to another page using the data:page/id, prefix:

The link value data:page/id,page-2 navigates to the ` with id="page-2"`.

---

2. Layer System

Layers are ` elements with parent="0". The default layer is id="1". Additional layers are added as sibling cells with parent="0"`.

Adding Layers

Assigning Content to Layers

Set the parent attribute on content cells to the layer's ID:

Layer Rules

| Rule | Enforcement | |------|-------------| | Layer cells have parent="0" | ALWAYS | | Layer cells have a value attribute (display name) | ALWAYS — shown in the Layers panel | | Default layer id="1" exists in every page | ALWAYS — mandatory | | Layer stacking follows XML document order | ALWAYS — earlier layers render BEHIND later layers | | visible="0" hides a layer and all its content | Use for annotation or draft layers | | Content cells reference their layer via parent | ALWAYS — parent="1" or parent="" |

Layer with Custom Properties

Wrap a layer cell in `` to attach metadata and enable placeholder inheritance:

Child cells of this layer inherit the env property for placeholder resolution.

---

3. Custom Properties via object Wrapper

To attach custom key-value metadata to any cell, wrap the ` in an element. and ` are functionally identical.

Structure

Attribute Placement Rules

| Attribute | On ` | On inner | |-----------|---------------|---------------------| | id | ALWAYS | NEVER | | label | ALWAYS (replaces value) | NEVER (value not used) | | tooltip | YES | NEVER | | link | YES | NEVER | | placeholders | YES | NEVER | | tags | YES | NEVER | | Custom attributes | YES | NEVER | | vertex / edge | NEVER | ALWAYS | | parent | NEVER | ALWAYS | | source / target | NEVER | ALWAYS (edges) | | style` | NEVER | ALWAYS |

Reserved Attributes on object

| Attribute | Purpose | |-----------|---------| | id | Unique identifier (REQUIRED) | | label | Display text (REQUIRED) | | tooltip | Hover text shown in the editor | | link | URL or internal page link | | placeholders | "1" to enable %variable% substitution | | tags | Comma-separated tags for search/filter |

Any attribute NOT in this list becomes a custom property visible in Edit Data (Ctrl+M).

---

4. File-Level Variables

File-level variables are defined as a JSON string in the vars attribute of ``. They are available to all cells on all pages.

Syntax

Rules

| Rule | Enforcement | |------|-------------| | vars value is a JSON string | ALWAYS | | vars attribute uses single quotes around the JSON | ALWAYS — double quotes break XML: vars='{"key":"val"}' | | JSON keys and values use double quotes inside | ALWAYS — valid JSON requires double-quoted strings | | File-level variables require ` wrapper | ALWAYS — NOT available with simplified ` format | | Variables are available across all pages | ALWAYS |

Accessing File-Level Variables

Use %variableName% in labels or tooltips. The containing cell MUST have placeholders="1":

Renders as: "Project: Atlas v2.1"

---

5. Placeholder System

Placeholders substitute %variableName% tokens in labels and tooltips with values from properties and variables.

Enabling Placeholders

Set placeholders="1" on the `` wrapper:

Resolution Order (First Match Wins)

Draw.io resolves %placeholder% by walking UP the containment hierarchy:

| Priority | Scope | Source | |----------|-------|--------| | 1 | Cell level | Attributes on the ` wrapper itself | | 2 | Parent container | Attributes on the parent group/container | | 3 | Ancestor containers | Continue upward through nested containers | | 4 | Layer level | Attributes on the layer cell (parent="0") | | 5 | Root cell | Attributes on (or its wrapper) | | 6 | File level | JSON variables in vars on ` |

If no match is found at any level, the placeholder renders as blank text.

Predefined Placeholders

These work without defining custom properties:

| Placeholder | Value | |-------------|-------| | %id% | Cell ID | | %width% | Cell width in pixels | | %height% | Cell height in pixels | | %length% | Edge length (edges only) | | %date% | Current date | | %time% | Current time | | %timestamp% | Full timestamp | | %date{format}% | Formatted date (Java SimpleDateFormat syntax) | | %page% | Current page name | | %pagenumber% | Current page number | | %pagecount% | Total page count | | %filename% | File name |

Unit conversion variants: %width:mm%, %height:in%, %width:m%.

Escaping Literal Percent Signs

Use %% to display a literal %:

Battery: 80%% charged  -->  "Battery: 80% charged"

---

6. Tooltips and Links

Tooltips

Set tooltip on the `` wrapper:

Tooltips support %placeholder% substitution when placeholders="1" is set.

External Links

Set link to a URL:

Internal Page Links

Link to another page within the same file using data:page/id,:

HTML Links in Labels

Links inside HTML labels use XML-escaped `` tags:

---

7. MathJax / LaTeX Support

Draw.io supports LaTeX math rendering via MathJax. Formulas are rendered inline in cell labels.

Enabling MathJax

Set math="1" on the `` element:

Inline Math

Use $$...$$ delimiters in the cell value:

Display Math (Block)

Use $$...$$ on its own line for display-mode rendering:

MathJax Rules

| Rule | Enforcement | |------|-------------| | math="1" on ` | ALWAYS — without it, LaTeX renders as plain text | | html=1 in the cell style | ALWAYS — MathJax requires HTML rendering | | $$...$$ delimiters around formulas | ALWAYS — this is the only supported delimiter | | XML-escape special characters in formulas | ALWAYS — has a unique id and a name`

• [ ] No `` elements are nested inside each other
• [ ] Every ` contains and `
• [ ] Cell IDs are unique across ALL pages
• [ ] vars attribute uses single-quoted JSON: vars='{"key":"val"}'
• [ ] placeholders="1" is set on every ` that uses %variable%` tokens
• [ ] ` wrappers have id and label; inner ` has neither
• [ ] math="1" is set on `` when LaTeX formulas are present
• [ ] Layer cells have parent="0" and a value attribute
• [ ] Internal page links use data:page/id, format
• [ ] compressed="false" is set on `` for AI-generated diagrams

References

• [references/methods.md](references/methods.md) — Complete attribute reference for pages, layers, variables, and placeholders
• [references/examples.md](references/examples.md) — Working XML examples for every metadata pattern
• [references/anti-patterns.md](references/anti-patterns.md) — What NOT to do, with explanations

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Impertio-Studio
• Source: Impertio-Studio/Draw.io-Claude-Skill-Package
• License: MIT

Install and usage instructions live in the source repository linked above.