---
name: drawio-format-adapter
description: draw.io XML format adapter. Converts logically organized content into standard XML format, ensuring correct tag semantics and standardized nesting.
---


# 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](.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](.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
<?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:**

| Attribute Name | Data Type | Required | Description | Default Value |
|--------|----------|----------|------|--------|
| version | string | No | File format version | None |
| host | string | No | Application that created this file | None |
| modified | string | No | Last modification time (ISO 8601 format) | None |
| agent | string | No | Client information that created this file | None |
| etag | string | No | Entity tag for cache control | None |
| type | string | No | File type identifier | None |

**Example:**
```xml
<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:**

| Attribute Name | Data Type | Required | Description | Default Value |
|--------|----------|----------|------|--------|
| name | string | Yes | Page name, displayed on page tab | "Page-1" |
| id | string | Yes | Page unique identifier | Auto-generated |

**Child Elements:**
- `mxGraphModel`: Contains actual graphic data (required and unique)

**Multi-page Example:**
```xml
<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:**

| Attribute Name | Data Type | Range | Default Value | Description |
|--------|----------|----------|--------|------|
| dx | number | Any value | 1422 | View horizontal offset (pixels) |
| dy | number | Any value | 762 | View vertical offset (pixels) |
| grid | boolean | 0, 1 | 1 | Whether to display grid |
| gridSize | number | > 0 | 10 | Grid size (pixels) |
| guides | boolean | 0, 1 | 1 | Whether to display alignment guides |
| tooltips | boolean | 0, 1 | 1 | Whether to enable tooltips |
| connect | boolean | 0, 1 | 1 | Whether to enable connection function |
| arrows | boolean | 0, 1 | 1 | Whether to display arrows |
| fold | boolean | 0, 1 | 1 | Whether to enable fold function |
| page | boolean | 0, 1 | 1 | Whether to display page boundaries |
| pageScale | number | > 0 | 1 | Page zoom ratio |
| pageWidth | number | > 0 | 827 | Page width (pixels, A4 paper approx 827px) |
| pageHeight | number | > 0 | 1169 | Page height (pixels, A4 paper approx 1169px) |
| math | boolean | 0, 1 | 0 | Whether to enable math typesetting (LaTeX support) |
| shadow | boolean | 0, 1 | 0 | Whether to display shadow effects |

**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:**
```xml
<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

| Attribute Name | Data Type | Required | Range | Default Value | Description |
|--------|----------|----------|----------|--------|------|
| id | string | Yes | Unique string | None | Element unique identifier, must be unique throughout the document |
| value | string | No | Any text | "" | Display text content, supports HTML entity encoding and HTML tags |
| style | string | No | Style string | "" | Style definition, multiple key-value pairs separated by semicolons |
| parent | string | Yes | Parent element ID | None | Parent element ID, determines element hierarchical relationship |
| visible | boolean | No | 0, 1 | 1 | Whether visible |
| collapsed | boolean | No | 0, 1 | 0 | Whether collapsed (for groups) |
| connectable | boolean | No | 0, 1 | 1 | Whether connectable |
| source | string | Conditionally required | Node ID | None | Edge's source node ID (only edges need this) |
| target | string | Conditionally required | Node ID | None | Edge's target node ID (only edges need this) |
| edge | boolean | Conditionally required | 0, 1 | 0 | Marked as edge (required for edges) |
| vertex | boolean | Conditionally required | 0, 1 | 0 | Marked as node (required for nodes) |
| placeholder | boolean | No | 0, 1 | 0 | Whether to use placeholder |

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

| Attribute Name | Data Type | Description |
|--------|----------|------|
| vertex | boolean | Must be set to 1, identifies this as a node |

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

| Attribute Name | Data Type | Required | Description |
|--------|----------|----------|------|
| edge | boolean | Yes | Must be set to 1, identifies this as an edge |
| source | string | Yes | Source node ID |
| target | string | Yes | Target node ID |
| value | string | No | Label text on edge |

## 2.2 mxGeometry Element

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

**Attribute Description:**

### 2.2.1 Node Geometric Attributes

| Attribute Name | Data Type | Required | Range | Default Value | Description |
|--------|----------|----------|----------|--------|------|
| x | number | No | Any value | 0 | Element top-left X coordinate (pixels) |
| y | number | No | Any value | 0 | Element top-left Y coordinate (pixels) |
| width | number | No | ≥ 0 | 0 | Element width (pixels) |
| height | number | No | ≥ 0 | 0 | Element height (pixels) |
| as | string | Yes | "geometry" | None | Fixed value, identifies this as geometric information |
| relative | boolean | No | 0, 1 | 0 | Whether to use relative coordinates |

### 2.2.2 Edge Geometric Attributes

| Attribute Name | Data Type | Required | Range | Default Value | Description |
|--------|----------|----------|----------|--------|------|
| relative | boolean | Yes | 0, 1 | 1 | Edge must use relative coordinates (set to 1) |
| as | string | Yes | "geometry" | None | Fixed value |

**Edge mxGeometry Child Elements:**

| Child Element | Description |
|--------|------|
| mxPoint (as="sourcePoint") | Source point coordinates (used when connection point is not at node center) |
| mxPoint (as="targetPoint") | Target point coordinates |
| mxPoint (as="offset") | Label offset |
| Array (as="points") | Path point array, defining polyline path |

**Edge Geometry Example:**
```xml
<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:**

| Attribute Name | Data Type | Required | Description |
|--------|----------|----------|------|
| x | number | Yes | X coordinate |
| y | number | Yes | Y coordinate |
| as | string | Conditionally required | Purpose identifier (sourcePoint/targetPoint/offset) |

## 2.3 Array Element

**Definition:** Used to store edge path point arrays.

**Attribute Description:**

| Attribute Name | Data Type | Required | Description |
|--------|----------|----------|------|
| as | string | Yes | Fixed value "points" |

**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](.reference/xml-reference.md#common-styles)

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

### 3.1.1 Rectangle

```xml
<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

```xml
<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

```xml
<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

```xml
<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

```xml
<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

```xml
<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](.reference/xml-reference.md#edges)

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

```xml
<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](.reference/xml-reference.md#containers-and-groups)

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

```xml
<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

```xml
<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

```xml
<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](.reference/xml-reference.md#html-labels)

**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](.reference/xml-reference.md#style-properties)

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](.reference/xml-reference.md#containers-and-groups)

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

### Basic Grouping Structure

```xml
<!-- 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.

```xml
<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](.reference/xml-reference.md#layers)

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

```xml
<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.

```xml
<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.

```xml
<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](.reference/xml-reference.md#metadata-and-placeholders)

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

```xml
<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`.

```xml
<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

```xml
<!-- 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

| UI Operation | XML Element | Attribute Change |
|----------|---------|----------|
| Insert rectangle | mxCell | vertex="1", style contains shape=rectangle |
| Insert ellipse | mxCell | vertex="1", style contains ellipse |
| Draw connector | mxCell | edge="1", source/target point to node IDs |
| Add text | mxCell | value attribute stores text content |
| Move element | mxGeometry | x/y coordinate change |
| Resize | mxGeometry | width/height change |
| Set color | style | fillColor/strokeColor change |
| Group operation | parent attribute | Child element parent points to group ID |

### 6.1.2 Style Correspondence

| UI Setting | style attribute | Example Value |
|----------|-----------|--------|
| Fill color | fillColor | #dae8fc, #FF0000 |
| Stroke color | strokeColor | #6c8ebf, none |
| Stroke width | strokeWidth | 1, 2, 3 |
| Font size | fontSize | 12, 14, 16 |
| Font color | fontColor | #333333 |
| Corner radius | arcSize | 10, 20, 50 |
| Shadow effect | shadow | 0, 1 |

### 6.1.3 Advanced Feature Correspondence

| UI Function | XML Implementation |
|----------|-------------|
| Fold/Expand | collapsed attribute, collapsible=1 style |
| Hyperlink | link attribute |
| Tooltip | tooltip attribute |
| Placeholder | placeholders="1" + custom attributes |
| Layer | Different parent containers |
| Alignment guides | guides=1 (mxGraphModel attribute) |
| Grid | grid=1, gridSize=10 |

## 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 `&#xa;` 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**
```python
# 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

| Color Name | Hexadecimal | Suggested Use |
|----------|----------|----------|
| Light Blue | #dae8fc | General nodes, services |
| Dark Blue | #6c8ebf | Borders, emphasis |
| Light Green | #d5e8d4 | Success, normal state |
| Dark Green | #82b366 | Borders, confirmation |
| Light Yellow | #fff2cc | Warning, attention |
| Dark Yellow | #d6b656 | Borders, warning |
| Light Red | #f8cecc | Error, danger |
| Dark Red | #b85450 | Borders, error |
| Light Purple | #e1d5e7 | Data, storage |
| Dark Purple | #9673a6 | Borders, data |
| Gray | #f5f5f5 | Background, grouping |
| Dark Gray | #666666 | Borders, text |

## 8.2 Semantic Color Schemes

| Semantic | Fill Color | Border Color |
|------|--------|--------|
| Input/Source | #dae8fc | #6c8ebf |
| Processing/Transform | #d5e8d4 | #82b366 |
| Output/Target | #e1d5e7 | #9673a6 |
| Decision | #fff2cc | #d6b656 |
| Exception/Error | #f8cecc | #b85450 |
| External System | #f5f5f5 | #666666 |

---

# 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:

```bash
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:

```bash
# 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