awesome-copilot/skills/draw-io-diagram-generator/references/drawio-xml-schema.md

draw.io XML Schema Reference

Complete reference for the .drawio file format (mxGraph XML). Use this when generating, parsing, or validating diagram files.

---

Top-Level Structure

Every .drawio file is XML with this root structure:

<!-- Set modified to the current ISO 8601 timestamp when generating a new file -->
<mxfile host="Electron" modified=""
        agent="draw.io" version="26.0.0" type="device">
  <diagram id="<unique-id>" name="<Page Name>">
    <mxGraphModel ...attributes...>
      <root>
        <mxCell id="0" />
        <mxCell id="1" parent="0" />
        <!-- All content cells here -->
      </root>
    </mxGraphModel>
  </diagram>
</mxfile>

<mxfile> Attributes

Attribute	Required	Default	Description
host	No	"app.diagrams.net"	Origin editor ("Electron" for desktop/VS Code)
modified	No	—	ISO 8601 timestamp
agent	No	—	User agent string
version	No	—	draw.io version
type	No	"device"	Storage type

<diagram> Attributes

Attribute	Required	Description
id	Yes	Unique page identifier (any string)
name	Yes	Tab label shown in editor

<mxGraphModel> Attributes

Attribute	Type	Default	Description
dx	int	1422	Scroll X offset
dy	int	762	Scroll Y offset
grid	0/1	1	Show grid
gridSize	int	10	Grid snap size in px
guides	0/1	1	Show alignment guides
tooltips	0/1	1	Enable tooltips
connect	0/1	1	Enable connection arrows on hover
arrows	0/1	1	Show directional arrows
fold	0/1	1	Enable group fold/collapse
page	0/1	1	Show page boundary
pageScale	float	1	Page zoom scale
pageWidth	int	1169	Page width in px (A4 landscape)
pageHeight	int	827	Page height in px (A4 landscape)
math	0/1	0	Enable LaTeX math rendering
shadow	0/1	0	Global shadow on shapes

Common page sizes (px at 96dpi):

Format	Width	Height
A4 landscape	1169	827
A4 portrait	827	1169
A3 landscape	1654	1169
Letter landscape	1100	850
Letter portrait	850	1100
Screen (16:9)	1654	931

---

Reserved Cells (Always Required)

<mxCell id="0" />                 <!-- Root cell — never omit, never add attributes -->
<mxCell id="1" parent="0" />     <!-- Default layer — all cells are children of this -->

These two cells MUST be the first entries inside <root>. IDs 0 and 1 are reserved and must not be used for any other cell.

---

Vertex (Shape) Element

<mxCell
  id="2"
  value="Label Text"
  style="rounded=1;whiteSpace=wrap;html=1;"
  vertex="1"
  parent="1">
  <mxGeometry x="200" y="160" width="120" height="60" as="geometry" />
</mxCell>

<mxCell> Vertex Attributes

Attribute	Required	Type	Description
id	Yes	string	Unique identifier within this diagram
value	Yes	string	Label text (HTML allowed if style has html=1)
style	Yes	string	Semicolon-delimited key=value style string
vertex	Yes	"1"	Must be "1" to declare this as a shape
parent	Yes	string	Parent cell ID ("1" for default layer)

<mxGeometry> Vertex Attributes

Attribute	Required	Type	Description
x	Yes	float	Left edge of shape (px from canvas origin)
y	Yes	float	Top edge of shape (px from canvas origin)
width	Yes	float	Shape width in px
height	Yes	float	Shape height in px
as	Yes	"geometry"	Always "geometry"

---

Edge (Connector) Element

<mxCell
  id="5"
  value="Label"
  style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;"
  edge="1"
  source="2"
  target="3"
  parent="1">
  <mxGeometry relative="1" as="geometry" />
</mxCell>

<mxCell> Edge Attributes

Attribute	Required	Type	Description
id	Yes	string	Unique identifier
value	Yes	string	Connector label (empty string for no label)
style	Yes	string	Style string (see Edge Styles)
edge	Yes	"1"	Must be "1" to declare as connector
source	No	string	ID of source vertex
target	No	string	ID of target vertex
parent	Yes	string	Parent cell ID (usually "1")

<mxGeometry> Edge Attributes

Attribute	Required	Type	Description
relative	No	"1"	Always "1" for edges
as	Yes	"geometry"	Always "geometry"

Edge with Label Offset

<mxGeometry x="-0.1" y="10" relative="1" as="geometry">
  <mxPoint as="offset" />
</mxGeometry>

The x on relative geometry moves the label along the edge (-1 to 1). y is perpendicular offset in px.

Edge with Manual Waypoints (Control Points)

<mxGeometry relative="1" as="geometry">
  <Array as="points">
    <mxPoint x="340" y="80" />
    <mxPoint x="340" y="200" />
  </Array>
</mxGeometry>

---

Multi-Page Diagrams

<mxfile>
  <diagram id="page-1" name="Overview">
    <mxGraphModel>...</mxGraphModel>
  </diagram>
  <diagram id="page-2" name="Detail">
    <mxGraphModel>...</mxGraphModel>
  </diagram>
</mxfile>

Each <diagram> is a separate page/tab. Cell IDs are scoped to their own <diagram> — the same ID value can appear in different pages without conflict.

---

Layer Cells

Layers replace the default id="1" layer. Cells are assigned to a layer via parent:

<mxCell id="0" />
<mxCell id="1" value="Background" parent="0" />        <!-- layer 1 -->
<mxCell id="layer2" value="Services" parent="0" />     <!-- layer 2 -->
<mxCell id="layer3" value="Connectors" parent="0" />   <!-- layer 3 -->

<!-- Assign layer via parent attribute -->
<mxCell id="10" value="API" ... parent="layer2">
  <mxGeometry ... />
</mxCell>

Toggle layer visibility:

<mxCell id="layer2" value="Services" parent="0" visible="0" />

---

Swimlane Container

<!-- Swimlane container -->
<mxCell id="swim1" value="Process" style="shape=pool;startSize=30;horizontal=1;" 
        vertex="1" parent="1">
  <mxGeometry x="40" y="40" width="800" height="340" as="geometry" />
</mxCell>

<!-- Lane 1 (child of swimlane container) -->
<mxCell id="lane1" value="Customer" style="swimlane;startSize=30;" 
        vertex="1" parent="swim1">
  <mxGeometry x="0" y="30" width="800" height="150" as="geometry" />
</mxCell>

<!-- Shape inside lane (child of lane) -->
<mxCell id="step1" value="Place Order" style="rounded=1;whiteSpace=wrap;html=1;" 
        vertex="1" parent="lane1">
  <mxGeometry x="80" y="50" width="120" height="60" as="geometry" />
</mxCell>

Key: Cells inside a swimlane have parent set to the lane's ID, not "1".
Coordinates inside lanes are relative to the lane origin.

---

Group Cells

<!-- Invisible group container -->
<mxCell id="group1" value="" style="group;" vertex="1" parent="1">
  <mxGeometry x="100" y="100" width="300" height="200" as="geometry" />
</mxCell>

<!-- Children relative to group origin -->
<mxCell id="child1" value="A" style="rounded=1;" vertex="1" parent="group1">
  <mxGeometry x="20" y="20" width="100" height="60" as="geometry" />
</mxCell>

---

HTML Labels

When html=1 is in the style, value can contain HTML:

<mxCell value="&lt;b&gt;OrderService&lt;/b&gt;&lt;br&gt;&lt;i&gt;:8080&lt;/i&gt;"
        style="rounded=1;html=1;" vertex="1" parent="1">
  <mxGeometry x="100" y="100" width="160" height="60" as="geometry" />
</mxCell>

HTML must be XML-escaped:

• < → <
• > → >
• & → &
• " → "

Common HTML tags supported: <b>, <i>, <u>, <br>, <font color="#hex">, <span style="...">, <hr/>

---

Tooltip / Metadata

<mxCell value="Service Name" tooltip="Handles order processing" style="..." vertex="1" parent="1">
  <mxGeometry ... />
</mxCell>

---

ID Generation Rules

Rule	Detail
IDs 0 and 1	Reserved — always the root and default layer
All other IDs	Must be unique within their <diagram>
Safe pattern	Sequential integers starting at 2, or UUID strings
Cross-page	IDs do not need to be unique across different <diagram> pages

Safe sequential ID example:

id="2", id="3", id="4", ...

UUID-style example:

id="a1b2c3d4-e5f6-7890-abcd-ef1234567890"

---

Coordinate System

• Origin (0, 0) is top-left of the canvas
• x increases rightward
• y increases downward
• All units are pixels

---

Recommended Spacing

Context	Value
Minimum gap between shapes	40px
Comfortable gap	80px
Swimlane inner padding	20px
Page margin from edge	40px
Connector routing clearance	10px

---

Minimal Valid .drawio File

<mxfile host="Electron" modified="2026-03-25T00:00:00.000Z" version="26.0.0">
  <diagram id="main" name="Page-1">
    <mxGraphModel dx="1422" dy="762" grid="1" gridSize="10" guides="1"
                  tooltips="1" connect="1" arrows="1" fold="1"
                  page="1" pageScale="1" pageWidth="1169" pageHeight="827"
                  math="0" shadow="0">
      <root>
        <mxCell id="0" />
        <mxCell id="1" parent="0" />
      </root>
    </mxGraphModel>
  </diagram>
</mxfile>

---

Validation Rules

Must Pass

• id="0" and id="1" cells always present as first two children of <root>
• No other cell uses id="0" or id="1"
• All id values are unique within each <diagram>
• Every <mxCell> has exactly one <mxGeometry> child
• <mxGeometry> has as="geometry" attribute
• Vertex cells have vertex="1", edge cells have edge="1"
• Edge source/target IDs reference existing vertex IDs in the same diagram
• Swimlane children have parent set to the swimlane/lane ID, not "1"
• HTML in value attributes is XML-escaped

Recommended

• Shapes do not overlap unless intentional (use ≥40px gap)
• Edge labels are short (≤4 words)
• Layer cells have descriptive value names
• All shapes fit within pageWidth × pageHeight bounds