Drawio Format Adapter

draw.io (diagrams.net) XML Format Detailed Documentation

This document provides detailed explanations of draw.io XML file structure, syntax rules, and usage methods, facilitating developers' understanding and use of draw.io XML format for programmatic generation and modification of graphics.

Important Note: This document focuses on XML file structure and core element attributes. First read reference/xml-reference.md. For detailed style properties, HTML tag usage, edge connections, container grouping, layer management, and other content, please refer to reference/xml-reference.md.

1. XML File Structure Definition

1.1 Overall File Structure

draw.io XML files use a hierarchical structure, forming a complete tree structure from the root element to the lowest-level graphic elements:

<?xml version="1.0" encoding="UTF-8"?>
<mxfile>
  <diagram name="Page-1" id="diagram-id">
    <mxGraphModel
      dx="1422"
      dy="762"
      grid="1"
      gridSize="10"
      guides="1"
      tooltips="1"
      connect="1"
      arrows="1"
      fold="1"
      page="1"
      pageScale="1"
      pageWidth="827"
      pageHeight="1169"
      math="0"
      shadow="0"
    >
      <root>
        <mxCell id="0" />
        <mxCell id="1" parent="0" />
        <!-- Graphic element definitions -->
      </root>
    </mxGraphModel>
  </diagram>
</mxfile>

1.2 Root Element mxfile

Definition: The root element of the XML document, containing one or more diagram elements.

Attribute Description:

Example:

<mxfile host="app.diagrams.net" modified="2024-01-15T08:30:00.000Z" agent="5.0" version="21.0.0" etag="abc123" type="device">

1.3 diagram Element

Definition: Represents an independent drawing page; a mxfile can contain multiple diagram elements.

Attribute Description:

Child Elements:

• mxGraphModel: Contains actual graphic data (required and unique)

Multi-page Example:

<mxfile>
  <diagram name="Architecture Diagram" id="page1">
    <mxGraphModel>...</mxGraphModel>
  </diagram>
  <diagram name="Flowchart" id="page2">
    <mxGraphModel>...</mxGraphModel>
  </diagram>
</mxfile>

1.4 mxGraphModel Element

Definition: The core container of the graphic model, defining global canvas attributes and coordinate system.

Attribute Description:

Child Elements:

• root: Container containing all graphic elements (required and unique)

1.5 root Element

Definition: Container for all graphic elements, using a flat storage structure.

Child Elements:

• Level 0: mxCell id="0" - Root node, no actual graphic meaning
• Level 1: mxCell id="1" parent="0" - Default parent container, parent of all top-level elements
• Other levels: Actual graphic elements (nodes and edges)

Structure Example:

<root>
  <mxCell id="0" />
  <mxCell id="1" parent="0" />
  <!-- User-created graphic elements below -->
  <mxCell id="2" vertex="1" parent="1">...</mxCell>
  <mxCell id="3" vertex="1" parent="1">...</mxCell>
  <mxCell id="4" edge="1" parent="1" source="2" target="3">...</mxCell>
</root>

2. Core Element Attribute Description

2.1 mxCell Element

Definition: mxCell is the most basic graphic unit in draw.io; all visible graphics (including nodes, edges, groups) are instances of mxCell.

Attribute Description:

2.1.1 Common Attributes

2.1.2 Node-specific Attributes (vertex="1")

2.1.3 Edge-specific Attributes (edge="1")

2.2 mxGeometry Element

Definition: Defines geometric position and dimension information for graphic elements.

Attribute Description:

2.2.1 Node Geometric Attributes

2.2.2 Edge Geometric Attributes

Edge mxGeometry Child Elements:

Edge Geometry Example:

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

2.2.3 mxPoint Element

Definition: Represents a 2D coordinate point.

Attribute Description:

2.3 Array Element

Definition: Used to store edge path point arrays.

Attribute Description:

Child Elements:

• Multiple mxPoint elements, defining various turning points of polyline path

3. XML Representation of Common Graphic Elements

3.1 Basic Shapes

See also: Common styles in reference/xml-reference.md

Common basic shapes include rectangle, ellipse, circle, rhombus, cylinder, etc. Standard examples can be found in xml-reference.md.

3.1.1 Rectangle

<mxCell id="rect1" value="Rectangle" vertex="1" parent="1">
  <mxGeometry x="100" y="100" width="120" height="60" as="geometry"/>
</mxCell>

3.1.2 Circle/Ellipse

<mxCell id="diamond1" value="Diamond" vertex="1" parent="1"
  style="rhombus;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;">
  <mxGeometry x="100" y="250" width="100" height="100" as="geometry"/>
</mxCell>

3.1.5 Cylinder

<mxCell id="cylinder1" value="Database" vertex="1" parent="1"
  style="shape=cylinder3;whiteSpace=wrap;html=1;boundedLbl=1;backgroundOutline=1;size=15;fillColor=#e1d5e7;strokeColor=#9673a6;">
  <mxGeometry x="300" y="250" width="100" height="80" as="geometry"/>
</mxCell>

3.1.6 Cloud Shape

<mxCell id="cloud1" value="Cloud" vertex="1" parent="1"
  style="ellipse;shape=cloud;whiteSpace=wrap;html=1;fillColor=#f5f5f5;strokeColor=#666666;">
  <mxGeometry x="500" y="250" width="120" height="80" as="geometry"/>
</mxCell>

3.1.7 Document/Page

<mxCell id="doc1" value="Document" vertex="1" parent="1"
  style="shape=note;whiteSpace=wrap;html=1;backgroundOutline=1;darkOpacity=0.05;fillColor=#ffff88;strokeColor=#36393d;">
  <mxGeometry x="100" y="400" width="80" height="100" as="geometry"/>
</mxCell>

3.1.8 Data Storage

<mxCell id="storage1" value="Data Storage" vertex="1" parent="1"
  style="shape=partialRectangle;whiteSpace=wrap;html=1;left=0;right=0;fillColor=none;strokeColor=#666666;">
  <mxGeometry x="300" y="400" width="100" height="60" as="geometry"/>
</mxCell>

3.2 Connector Lines (Edges)

See also: Edge connection description in xml-reference.md

Connector lines (edges) are used to connect various nodes. Common styles include straight lines, arrowed connections, dashed lines, polylines, etc. Detailed examples and automatic routing explanations can be found in xml-reference.md.

Basic Edge Structure

<mxCell id="edge1" edge="1" parent="1" source="rect1" target="ellipse1">
  <mxGeometry relative="1" as="geometry"/>
</mxCell>

Note: Each edge's mxCell must contain a <mxGeometry relative="1" as="geometry" /> child element.

3.3 Swimlane Diagram Elements

See also: Containers and groups in xml-reference.md

Swimlane diagrams are used for cross-functional flowcharts. Include basic swimlanes, vertical swimlanes, BPMN-style swimlanes, etc. Detailed usage can be found in xml-reference.md.

3.4 UML Elements

UML class diagrams, interfaces, relationships (inheritance, implementation, association, composition, etc.) can be implemented using specialized styles. Examples can be found in xml-reference.md style descriptions.

Basic UML Class Structure

<mxCell id="class1" value="&lt;b&gt;ClassName&lt;/b&gt;&#xa;- attribute: Type&#xa;+ method(): ReturnType"
  vertex="1" parent="1"
  style="swimlane;fontStyle=1;align=center;verticalAlign=top;childLayout=stackLayout;horizontal=1;startSize=26;horizontalStack=0;resizeParent=1;resizeParentMax=0;resizeLast=0;collapsible=1;marginBottom=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;">
  <mxGeometry x="100" y="100" width="160" height="100" as="geometry"/>
</mxCell>

3.5 Flowchart Elements

Standard flowchart elements include: start/end (rounded rectangle), process (rectangle), decision (rhombus), input/output (parallelogram), etc. These can all be implemented through different shape styles.

Start Node

<mxCell id="start1" value="Start" vertex="1" parent="1"
  style="rounded=1;whiteSpace=wrap;html=1;fillColor=#d5e8d4;strokeColor=#82b366;arcSize=50;">
  <mxGeometry x="100" y="100" width="80" height="40" as="geometry"/>
</mxCell>

Decision Node

<mxCell id="decision1" value="Decision?" vertex="1" parent="1"
  style="rhombus;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;">
  <mxGeometry x="450" y="90" width="80" height="80" as="geometry"/>
</mxCell>

4. Style Definition (style attribute) Detailed Explanation

See also: HTML tag usage explanation in xml-reference.md

Important Note: When using HTML tags (such as <b>, <br>, <i>, <u>, etc.), you must include html=1 in the style.

4.1 Style Syntax Rules

4.1.1 Basic Format

The style attribute is a semicolon-separated key-value pair string:

key1=value1;key2=value2;key3=value3;

Rule Description:

1. Each key-value pair ends with a semicolon ;
2. Key name and value are connected with an equals sign =
3. Key names are case-sensitive
4. Values can be strings, numbers, or booleans (0/1)
5. The semicolon after the last key-value pair can be omitted, but it's recommended to keep it

4.1.2 Style Inheritance and Overriding

• Child elements inherit parent element styles
• Later-defined styles override earlier-defined identical styles
• Use ; to separate multiple style definitions

4.2 Common Style Key-Value Pairs

See also: Style property description in xml-reference.md

Style properties include shape, fill, stroke, text, edge/arrow, connection points, container/grouping, image, and other types. Complete tables can be found in xml-reference.md.

Quick reference for common style key-value pairs:

• Shape styles: shape, rounded, aspect
• Fill styles: fillColor, gradientColor, shadow
• Stroke styles: strokeColor, strokeWidth, dashed
• Text styles: fontColor, fontSize, fontStyle, align, html
• Edge styles: endArrow, edgeStyle, curved
• Container styles: container, collapsible, startSize

5. Implementation of Special Features

5.1 Grouping

See also: Containers and groups in xml-reference.md

Grouping organizes multiple elements together for unified movement, scaling, and collapsing.

Basic Grouping Structure

<!-- Group container -->
<mxCell id="group1" value="Group Title" vertex="1" parent="1"
  style="group;fillColor=none;strokeColor=default;verticalAlign=top;fontStyle=1;"
  connectable="0" collapsible="1">
  <mxGeometry x="100" y="100" width="300" height="200" as="geometry"/>
</mxCell>

<!-- Child elements in group, parent points to group -->
<mxCell id="child1" value="Child Element 1" vertex="1" parent="group1"
  style="rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;">
  <mxGeometry x="20" y="40" width="100" height="60" as="geometry"/>
</mxCell>

Key Points:

• Group container uses style="group"
• Child elements' parent attribute points to the group container's ID
• Child elements' geometric coordinates are relative to the group

5.2 Folding

Collapsible containers use collapsible=1 and collapsed attributes to control fold state.

<mxCell id="foldable1" value="Collapsible Container" vertex="1" parent="1"
  style="swimlane;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;startSize=30;collapsible=1;"
  collapsed="0">
  <mxGeometry x="100" y="100" width="200" height="150" as="geometry"/>
</mxCell>

Attribute Description:

• collapsible=1: Enable folding function
• collapsed="0": Initial expanded state (0=expanded, 1=collapsed)
• startSize: Title bar size retained after folding

5.3 Layers

See also: Layer description in xml-reference.md

Layers control visibility and z-order. Each element belongs to a layer; element display can be controlled by switching layers.

<mxGraphModel>
  <root>
    <mxCell id="0"/>
    <mxCell id="1" parent="0"/>
    <mxCell id="2" value="Layer Name" parent="0"/>
    <!-- Elements in layer 2 -->
    <mxCell id="20" value="Node" style="..." vertex="1" parent="2">
      <mxGeometry x="100" y="100" width="120" height="60" as="geometry"/>
    </mxCell>
  </root>
</mxGraphModel>

5.4 Hyperlinks

Add hyperlinks to nodes via the link attribute.

<mxCell id="link1" value="Click to Visit" vertex="1" parent="1"
  style="rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontColor=#0000FF;underline=1;"
  link="https://www.example.com">
  <mxGeometry x="100" y="100" width="120" height="40" as="geometry"/>
</mxCell>

Attribute Description:

• link: Target URL or internal page reference
• fontColor=#0000FF and underline=1: Visual cue indicating this is a link

5.5 Tooltips

Add hover tooltips to nodes via the tooltip attribute.

<mxCell id="tooltip1" value="Hover to View" vertex="1" parent="1"
  style="rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;"
  tooltip="This is detailed tooltip information">
  <mxGeometry x="100" y="200" width="120" height="40" as="geometry"/>
</mxCell>

5.6 Placeholders

See also: Metadata and placeholders in xml-reference.md

Placeholders allow referencing element attribute values in text using %propertyName% syntax.

<mxCell id="placeholder1" value="Name: %name%" vertex="1" parent="1"
  style="rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;"
  placeholders="1"
  name="Example Name">
  <mxGeometry x="100" y="300" width="150" height="60" as="geometry"/>
</mxCell>

System placeholders: %id%, %value%, %parent%, %source%, %target%, %width%, %height%, etc.

5.7 Connection Point Control

Control edge connection positions via exitX/Y and entryX/Y.

<mxCell id="edge1" edge="1" parent="1" source="node1" target="node2"
  style="endArrow=classic;html=1;strokeColor=#666666;exitX=1;exitY=0.5;entryX=0;entryY=0.5;">
  <mxGeometry relative="1" as="geometry"/>
</mxCell>

Description:

• exitX=1;exitY=0.5: Exit from the center of the right side of source node
• entryX=0;entryY=0.5: Enter at the center of the left side of target node
• Value range is 0-1, indicating relative position

5.8 Layers

5.8.1 Creating Layers

<!-- Layer container -->
<mxCell id="layer1" value="Background Layer" vertex="1" parent="0"
  style="locked=1;"
  visible="1">
  <mxGeometry x="0" y="0" width="0" height="0" as="geometry"/>
</mxCell>

<!-- Default layer -->
<mxCell id="1" parent="0"/>

<!-- Elements in background layer -->
<mxCell id="bg1" value="" vertex="1" parent="layer1"
  style="rounded=0;whiteSpace=wrap;html=1;fillColor=#f5f5f5;strokeColor=none;">
  <mxGeometry x="0" y="0" width="827" height="1169" as="geometry"/>
</mxCell>

6. XML to UI Operation Correspondence and Import/Export

6.1 XML to UI Operation Correspondence

6.1.1 Basic Element Correspondence

6.1.2 Style Correspondence

6.1.3 Advanced Feature Correspondence

6.2 Import/Export Notes

6.2.1 Importing XML into draw.io

Method 1: Direct Open

1. Save XML as a .drawio or .xml file
2. In draw.io, select "File" → "Open"
3. Select the saved XML file

Method 2: Import from Text

1. In draw.io, select "Arrange" → "Insert" → "Advanced" → "CSV"
2. Or use "File" → "Import From" → "Device"

Method 3: Drag and Drop Import Directly drag the XML file into the draw.io editor

6.2.2 Exporting XML from draw.io

Method 1: Save as File

1. "File" → "Save As"
2. Select location and save as .drawio file

Method 2: Export as XML

1. "File" → "Export As" → "XML"
2. Choose compressed or uncompressed format

Method 3: View Source Code

1. "Extras" → "Edit Diagram" → "Source"
2. Directly copy XML content

6.2.3 Precautions

1. ID Uniqueness

• All mxCell element IDs must be unique throughout the document
• Recommended ID format: prefix + number (e.g., node1, edge1, group1)
• Avoid using special characters and spaces

2. Parent Relationship

• Root node id="0" and default container id="1" must exist
• All graphic elements' parent should point to "1" or other valid container
• Incorrect parent causes elements to be invisible or have abnormal positions

3. Encoding Issues

• XML files should use UTF-8 encoding
• Special characters (such as <, >, &) should use HTML entity encoding
• Use 
 for line breaks

4. Coordinate System

• Coordinate origin (0,0) is at top-left
• X axis increases rightward, Y axis increases downward
• Unit is pixels

5. Style Syntax

• Style strings are semicolon-separated
• Boolean values use 0 and 1
• Colors use #RRGGBB format

6. Compatibility

• Different versions of draw.io may support different style attributes
• Recommended to test display effect after import
• Complex graphics may have differences between versions

7. Compressed Format

• draw.io supports compressed XML format (base64 encoded)
• Compressed format files are smaller but unreadable
• Programmatic generation should use uncompressed format

6.2.4 Programmatic Generation Recommendations

Best Practices

1. Template-based Generation

# Pseudo-code example
def create_node(id, value, x, y, width, height, style):
    return f'''<mxCell id="{id}" value="{value}" vertex="1" parent="1" style="{style}">
  <mxGeometry x="{x}" y="{y}" width="{width}" height="{height}" as="geometry"/>
</mxCell>'''

2. ID Management

• Use counters or UUIDs to generate unique IDs
• Maintain ID mapping table for edge creation

3. Style Management

• Predefined style templates
• Use style inheritance to reduce duplication

4. Validation Checks

• Check all IDs are unique
• Verify parent references are valid
• Ensure geometric attributes are non-negative

5. Version Declaration

• Include version information in mxfile element
• Note generation tool and date

7. Other Organization Formats

7.1 Content Placement Notes

• An item without connecting lines is an orphan item. Orphan items can only appear as comments or descriptions, not as main content.

• Lines cannot cross each other.

• Items cannot cross or overlap with each other.

• Lines cannot pass through items.

8. Appendix: Common Color Reference

8.1 Standard Colors

8.2 Semantic Color Schemes

9. Format Checking

9.1 Generated drawio files in XML format should not contain any XML comments (<!-- -->), otherwise the file will not display properly.

9.2 Pay attention to ID naming to avoid namespace conflicts: "Ensure all mxCell IDs are prefixed with 'cell_' to avoid JavaScript reserved word conflicts (e.g., use 'cell_constructor' instead of 'constructor')."

9.3 Use xmllint tool for XML format validation

9.3.1 Check Installation

Use the following command to check if xmllint is installed:

chmod +x scripts/check_xmllint_install.sh
bash scripts/check_xmllint_install.sh

9.3.2 Validate XML File

Use the following command to validate the XML file:

# check the xml file
xmllint --noout file_name.drawio
# check the xml string
echo '<root><node attr="val">Context</node></root>' | xmllint --noout -

If the XML format is correct, there will be no output. If there are format errors, xmllint will report the specific error and line number.Then you can fix the XML format according to the error message.

After the XML format is fixed, you must use the xmllint tool to check the format again ** until there are no errors **. Only XML files that pass xmllint validation can be successfully imported into draw.io.

10. Summary

This document provides detailed explanations of draw.io XML format specifications, including:

1. File Structure: Hierarchical relationships from mxfile to mxCell
2. Core Elements: Complete attribute descriptions for mxGraphModel, mxCell, mxGeometry
3. Graphic Elements: XML representations of basic shapes, connectors, UML elements, flowchart elements
4. Style System: Syntax rules and common key-value pairs for style attributes
5. Advanced Features: Implementation methods for grouping, folding, hyperlinks, tooltips
6. Complete Examples: 5 XML examples for different scenarios
7. Import/Export: Correspondence between XML and UI operations and precautions

After mastering this knowledge, developers can:

• Programmatically generate complex draw.io graphics
• Batch convert other formats to draw.io XML
• Automate graphic generation and modification workflows
• Build visualization tools based on draw.io