next-ai-draw-io/app/api/chat/xml_guide.md

Draw.io XML Schema Guide

This guide explains the structure of draw.io (diagrams.net) XML files to help you understand and create diagrams programmatically.

Basic Structure

A draw.io XML file has the following hierarchy:

<mxfile>
  <diagram>
    <mxGraphModel>
      <root>
        <mxCell /> <!-- Cells that make up the diagram -->
      </root>
    </mxGraphModel>
  </diagram>
</mxfile>

Root Element: <mxfile>

The root element of a draw.io file.

Attributes:

• host: The application that created the file (e.g., "app.diagrams.net")
• modified: Last modification timestamp
• agent: Browser / user agent information
• version: Version of the application
• type: File type (usually "device" or "google")

Example:

<mxfile host="app.diagrams.net" modified="2023-07-14T10:20:30.123Z" agent="Mozilla/5.0" version="21.5.2" type="device">

Diagram Element: <diagram>

Each page in your draw.io document is represented by a <diagram> element.

Attributes:

• id: Unique identifier for the diagram
• name: The name of the diagram / page

Example:

<diagram id="pWHN0msd4Ud1ZK5cD-Hr" name="Page-1">

Graph Model: <mxGraphModel>

Contains the actual diagram data.

Attributes:

• dx: Grid size in x-direction (usually 1)
• dy: Grid size in y-direction (usually 1)
• grid: Whether grid is enabled (0 or 1)
• gridSize: Grid cell size (usually 10)
• guides: Whether guides are enabled (0 or 1)
• tooltips: Whether tooltips are enabled (0 or 1)
• connect: Whether connections are enabled (0 or 1)
• arrows: Whether arrows are enabled (0 or 1)
• fold: Whether folding is enabled (0 or 1)
• page: Whether page view is enabled (0 or 1)
• pageScale: Scale of the page (usually 1)
• pageWidth: Width of the page (e.g., 850)
• pageHeight: Height of the page (e.g., 1100)
• math: Whether math typesetting is enabled (0 or 1)
• shadow: Whether shadows are enabled (0 or 1)

Example:

<mxGraphModel dx="1" dy="1" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="850" pageHeight="1100" math="0" shadow="0">

Root Cell Container: <root>

Contains all the cells in the diagram.

Example:

<root>
<mxCell id="0"/>
<mxCell id="1" parent="0"/>

  <!-- Other cells go here -->
</root>

Cell Elements: <mxCell>

The basic building block of diagrams. Cells represent shapes, connectors, text, etc.

Attributes for all cells:

• id: Unique identifier for the cell
• parent: ID of the parent cell (typically "1" for most cells)
• value: Text content of the cell
• style: Styling information (see Style section below)

Attributes for shapes (vertices):

• vertex: Set to "1" for shapes
  • connectable: Whether the shape can be connected (0 or 1)

Attributes for connectors (edges):

• edge: Set to "1" for connectors
  • source: ID of the source cell
  • target: ID of the target cell

Example (Rectangle shape):

<mxCell id="2" value="Hello World" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1">
  <mxGeometry x="350" y="190" width="120" height="60" as="geometry"/>
</mxCell>

Example (Connector):

<mxCell id="3" value="" style="endArrow=classic;html=1;rounded=0;" edge="1" parent="1" source="2" target="4">
  <mxGeometry width="50" height="50" relative="1" as="geometry">
    <mxPoint x="400" y="430" as="sourcePoint"/>
    <mxPoint x="450" y="380" as="targetPoint"/>
  </mxGeometry>
</mxCell>

Geometry: <mxGeometry>

Defines the position and dimensions of cells.

Attributes for shapes:

• x: The x-coordinate of the top-left point of the shape.
• y: The y-coordinate of the top-left point of the shape.
• width: The width of the shape.
• height: The height of the shape.
• as: Specifies the role of this geometry within its parent cell. Typically set to "geometry" for the main shape definition.

Attributes for connectors:

• relative: Set to "1" for relative geometry
• as: Set to "geometry"

Example for shapes:

<mxGeometry x="350" y="190" width="120" height="60" as="geometry"/>

Example for connectors:

<mxGeometry width="50" height="50" relative="1" as="geometry">
  <mxPoint x="400" y="430" as="sourcePoint"/>
  <mxPoint x="450" y="380" as="targetPoint"/>
</mxGeometry>

Cell Style Reference

Styles are specified as semicolon-separated key=value pairs in the style attribute of <mxCell> elements.

Shape-specific Styles

• Rectangle: shape=rectangle
• Ellipse: shape=ellipse
• Triangle: shape=triangle
• Rhombus: shape=rhombus
• Hexagon: shape=hexagon
• Cloud: shape=cloud
• Actor: shape=actor
• Cylinder: shape=cylinder
• Document: shape=document
• Note: shape=note
• Card: shape=card
• Parallelogram: shape=parallelogram

Connector Styles

• endArrow=classic: Arrow type at the end (classic, open, oval, diamond, block)
• startArrow=none: Arrow type at the start (none, classic, open, oval, diamond)
• curved=1: Curved connector (0 or 1)
• edgeStyle=orthogonalEdgeStyle: Connector routing style
• elbow=vertical: Elbow direction (vertical, horizontal)
• jumpStyle=arc: Jump style for line crossing (arc, gap)
• jumpSize=10: Size of the jump

Special Cells

Draw.io files contain two special cells that are always present:

1. Root Cell (id = "0"): The parent of all cells
2. Default Parent Cell (id = "1", parent = "0"): The default layer and parent for most cells

Tips for Manually Creating Draw.io XML

1. Start with the basic structure (mxfile, diagram, mxGraphModel, root)
2. Always include the two special cells (id = "0" and id = "1")
3. Assign unique and sequential IDs to all cells
4. Define parent relationships correctly
5. Use mxGeometry elements to position shapes
6. For connectors, specify source and target attributes
7. CRITICAL: All mxCell elements must be DIRECT children of <root>. NEVER nest mxCell inside another mxCell.

Common Patterns

Grouping Elements

To group elements, create a parent cell and set other cells' parent attribute to its ID:

<!-- Group container -->
<mxCell id="10" value="Group" style="group" vertex="1" connectable="0" parent="1">
  <mxGeometry x="200" y="200" width="200" height="100" as="geometry" />
</mxCell>
<!-- Elements inside the group -->
<mxCell id="11" value="Element 1" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="10">
  <mxGeometry width="90" height="40" as="geometry" />
</mxCell>
<mxCell id="12" value="Element 2" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="10">
  <mxGeometry x="110" width="90" height="40" as="geometry" />
</mxCell>

Swimlanes

Swimlanes use the swimlane shape style. IMPORTANT: All mxCell elements (swimlanes, steps, and edges) must be siblings under <root>. Edges are NOT nested inside swimlanes or steps.

<root>
  <mxCell id="0"/>
  <mxCell id="1" parent="0"/>
  <!-- Swimlane 1 -->
  <mxCell id="lane1" value="Frontend" style="swimlane;startSize=30;" vertex="1" parent="1">
    <mxGeometry x="40" y="40" width="200" height="300" as="geometry"/>
  </mxCell>
  <!-- Swimlane 2 -->
  <mxCell id="lane2" value="Backend" style="swimlane;startSize=30;" vertex="1" parent="1">
    <mxGeometry x="280" y="40" width="200" height="300" as="geometry"/>
  </mxCell>
  <!-- Step inside lane1 (parent="lane1") -->
  <mxCell id="step1" value="Send Request" style="rounded=1;" vertex="1" parent="lane1">
    <mxGeometry x="20" y="60" width="160" height="40" as="geometry"/>
  </mxCell>
  <!-- Step inside lane2 (parent="lane2") -->
  <mxCell id="step2" value="Process" style="rounded=1;" vertex="1" parent="lane2">
    <mxGeometry x="20" y="60" width="160" height="40" as="geometry"/>
  </mxCell>
  <!-- Edge connecting step1 to step2 (sibling element, NOT nested inside steps) -->
  <mxCell id="edge1" style="edgeStyle=orthogonalEdgeStyle;endArrow=classic;" edge="1" parent="1" source="step1" target="step2">
    <mxGeometry relative="1" as="geometry"/>
  </mxCell>
</root>

Tables

Tables use multiple cells with parent-child relationships:

<mxCell id="30" value="Table" style="shape=table;startSize=30;container=1;collapsible=1;childLayout=tableLayout;fixedRows=1;rowLines=0;fontStyle=1;align=center;resizeLast=1;html=1;" vertex="1" parent="1">
  <mxGeometry x="200" y="200" width="180" height="120" as="geometry" />
</mxCell>
<mxCell id="31" value="" style="shape=tableRow;horizontal=0;startSize=0;swimlaneHead=0;swimlaneBody=0;fillColor=none;collapsible=0;dropTarget=0;points=[0,0.5,1,0.5];portConstraint=eastwest;top=0;left=0;right=0;bottom=1;" vertex="1" parent="30">
  <mxGeometry y="30" width="180" height="30" as="geometry" />
</mxCell>

Advanced Features

Custom Attributes

Draw.io allows adding custom attributes to cells:

<mxCell id="40" value="Custom Element" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1">
  <mxGeometry x="200" y="200" width="120" height="60" as="geometry"/>
  <Object label="Custom Label" customAttr="value" />
</mxCell>

These custom attributes can store additional metadata or be used by plugins and custom behaviors.

User-defined Styles

You can define custom styles for cells by combining various style attributes:

<mxCell id="50" value="Custom Styled Cell"
      style="shape=hexagon;perimeter=hexagonPerimeter2;whiteSpace=wrap;html=1;fixedSize=1;fillColor=#f8cecc;strokeColor=#b85450;strokeWidth=2;fontSize=14;fontStyle=1"
      vertex="1" parent="1">
  <mxGeometry x="300" y="200" width="120" height="80" as="geometry"/>
</mxCell>

Layers

You can create multiple layers in a diagram to organize complex diagrams:

<!-- Default layer (always present) -->
<mxCell id="1" parent="0"/>

<!-- Additional custom layer -->
<mxCell id="60" value="Layer 2" style="locked=0;group=" parent="0"/>

<!-- Elements in Layer 2 -->
<mxCell id="61" value="Element in Layer 2" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="60">
  <mxGeometry x="200" y="300" width="120" height="60" as="geometry"/>
</mxCell>