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
parentset 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="<b>OrderService</b><br><i>:8080</i>"
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 xincreases rightwardyincreases 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"andid="1"cells always present as first two children of<root> - [ ] No other cell uses
id="0"orid="1" - [ ] All
idvalues are unique within each<diagram> - [ ] Every
<mxCell>has exactly one<mxGeometry>child - [ ]
<mxGeometry>hasas="geometry"attribute - [ ] Vertex cells have
vertex="1", edge cells haveedge="1" - [ ] Edge
source/targetIDs reference existing vertex IDs in the same diagram - [ ] Swimlane children have
parentset to the swimlane/lane ID, not"1" - [ ] HTML in
valueattributes is XML-escaped
Recommended
- [ ] Shapes do not overlap unless intentional (use ≥40px gap)
- [ ] Edge labels are short (≤4 words)
- [ ] Layer cells have descriptive
valuenames - [ ] All shapes fit within
pageWidth×pageHeightbounds