/draw-io-diagram-generator

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

<diagram> Attributes

<mxGraphModel> Attributes

Common page sizes (px at 96dpi):

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

<mxGeometry> Vertex Attributes

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

<mxGeometry> Edge Attributes

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

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

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