Skip to main content

The .drawio file format

A draw.io diagram file (.drawio) is an XML document. The root element mxfile contains one diagram element per page. Each page contains an mxGraphModel with the cells of the page: layers, shapes, connectors and groups. .drawio.svg and .drawio.png images contain the same XML document, so that they can be opened and edited in draw.io.

The XML Schema for the format is described in §6.

1. File names and media type​

File nameContent
.drawioThe XML document described on this page. Media type application/vnd.jgraph.mxfile.
.drawio.svgAn SVG image of the diagram that contains the XML document, §5.1.
.drawio.pngA PNG image of the diagram that contains the XML document, §5.2.
.xmlThe same XML document with an XML declaration, from File > Export as > XML.

The double extensions .drawio.svg and .drawio.png tell tools, such as the draw.io extension for VS Code, that an image contains a diagram.

2. Structure​

mxfile                             the file, §2.1
└─ diagram one per page, §2.2
└─ mxGraphModel page settings, §2.3
└─ root all cells of the page, §2.4
├─ mxCell id="0" root cell
├─ mxCell id="1" default layer, parent="0"
├─ mxCell vertex="1" shape, parent="1"
│ └─ mxGeometry position and size, §2.5
├─ mxCell edge="1" connector, parent="1"
│ └─ mxGeometry
└─ UserObject cell with custom properties, §2.6
└─ mxCell

Cells aren't nested in each other in the XML. root lists all cells of the page, and each cell names its parent in parent.

2.1 mxfile​

AttributeDescription
hostWhere the file was last saved, for example app.diagrams.net, or Electron for draw.io Desktop.
pagesNumber of pages, written for files with more than one page.
compressedtrue if draw.io saves the pages of this file in the compressed form (§4), false if not. Set with File > Properties > Compressed.
varsFile properties for placeholders, as a JSON object, for example {"project":"Atlas"}. Set with File > Properties > Edit Data.

Files can contain more attributes, such as agent, modified, version and etag. They describe the program and the time of the save, and don't change the diagram.

2.2 diagram​

AttributeDescription
idPage ID, unique in the file.
namePage name, shown in the page tab.

The content of diagram is either one mxGraphModel element (plain form), or the mxGraphModel as compressed text (compressed form, §4).

2.3 mxGraphModel​

The attributes are the settings of the page. All are optional. 1 is on, 0 is off.

AttributeDescription
dx, dyScroll position when the file was saved.
grid, gridSizeGrid on or off, and the grid size in px.
page, pageScale, pageWidth, pageHeightPage view on or off, page scale, and page size in px. 850 × 1100 is US Letter.
backgroundPage colour, for example #ffffff, or none.
shadowShadow on all shapes.
mathMathematical typesetting in labels.
adaptiveColorsColours in dark mode: auto, simple or none.
guides, tooltips, connect, arrows, foldEditor options: alignment guides, tooltips, connections, connection arrows, and collapsing containers.

mxGraphModel contains one root element. With style compression, a defs element before root holds the shared images and shapes.

2.4 root and mxCell​

Every page has a root cell without a parent, and at least one layer: a cell whose parent is the root cell. draw.io gives them the IDs 0 and 1. More layers are more cells with parent="0", and their value is the layer name. Shapes and connectors have a layer, a group or a container as their parent.

Within a parent, a cell later in the list is drawn on top of the cells before it. A later layer is drawn on top of the layers before it.

AttributeDescription
idCell ID, unique in the page. Any string.
parentID of the parent cell.
valueThe label. HTML if the style contains html=1, escaped as XML in the attribute: <b>Bold</b>.
styleThe style, §2.7.
vertex1 for shapes, including text, groups and containers.
edge1 for connectors.
source, targetIDs of the cells that the ends of a connector are connected to.
connectable0 if connectors can't be connected to the cell.
collapsed1 if a container is collapsed.
visible0 if the cell is hidden.

A connector label is a cell with vertex="1", the connector as its parent, and a relative geometry (§2.5).

2.5 mxGeometry​

Each shape and connector has one mxGeometry child with as="geometry". Coordinates are in px. x increases to the right, y increases downwards. The position of a cell in a group or container is relative to the top-left corner of its parent.

AttributeDescription
x, yPosition of the top-left corner.
width, heightSize.
relative1 for connectors and connector labels. In a connector label, x is the position along the connector, from -1 (start) to 1 (end), and y is the distance from the connector in px.
asAlways geometry.
Child elementDescription
mxPoint as="sourcePoint", mxPoint as="targetPoint"Start and end point of a connector end that isn't connected.
Array as="points"Waypoints of a connector, as mxPoint elements.
mxPoint as="offset"Offset of the label in px.
mxRectangle as="alternateBounds"Size of a container in its other state, collapsed or expanded.

2.6 UserObject and object​

A cell with custom properties, a link, a tooltip or tags is wrapped in UserObject, or in object, which has the same meaning. The wrapper has the id, the label in label instead of value, and the properties as attributes. The mxCell inside has no id.

<UserObject id="2" label="Web server" tooltip="Runs the shop" ip="10.0.0.5">
<mxCell style="rounded=1;whiteSpace=wrap;html=1;" vertex="1" parent="1">
<mxGeometry x="40" y="40" width="120" height="60" as="geometry" />
</mxCell>
</UserObject>
AttributeDescription
labelThe label.
tooltipTooltip text.
linkLink that opens when the cell is clicked.
tagsTags, separated by spaces.
placeholders1 to replace %name% in the label with the value of the property name. See placeholders.

All other attributes are custom properties.

2.7 Styles​

style is a list of key=value pairs, separated by ;:

rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;
  • A name without = at the start applies a named style, for example ellipse or text.
  • Keys and values are case-sensitive. 1 is on, 0 is off. Colours are #rrggbb or none.
  • Keys that draw.io doesn't know are ignored.

All keys and values are listed in the style reference.

3. Minimal example​

A complete file with two shapes and a connector:

<mxfile>
<diagram id="page-1" name="Page-1">
<mxGraphModel grid="1" gridSize="10" page="1" pageWidth="850" pageHeight="1100">
<root>
<mxCell id="0" />
<mxCell id="1" parent="0" />
<mxCell id="2" value="Idea" style="rounded=1;whiteSpace=wrap;html=1;" vertex="1" parent="1">
<mxGeometry x="40" y="40" width="120" height="60" as="geometry" />
</mxCell>
<mxCell id="3" value="Diagram" style="rounded=1;whiteSpace=wrap;html=1;" vertex="1" parent="1">
<mxGeometry x="240" y="40" width="120" height="60" as="geometry" />
</mxCell>
<mxCell id="4" style="edgeStyle=orthogonalEdgeStyle;html=1;" edge="1" parent="1" source="2" target="3">
<mxGeometry relative="1" as="geometry" />
</mxCell>
</root>
</mxGraphModel>
</diagram>
</mxfile>

draw.io also opens a file that contains only the mxGraphModel element, and adds mxfile and diagram around it. The XML Schema (§6) only accepts files with mxfile.

4. Compressed form​

In the compressed form, diagram contains text instead of the mxGraphModel element: the mxGraphModel XML of the page, encoded in three steps.

  1. URL-encode the XML as JavaScript's encodeURIComponent does.
  2. Compress the result with raw DEFLATE (RFC 1951, without a zlib header or checksum).
  3. Encode the compressed bytes as Base64.

To read a compressed page, reverse the steps: decode the Base64, inflate the raw DEFLATE data, and URL-decode the result.

draw.io saves the plain form, unless the file has compressed="true", set with File > Properties > Compressed, or the configuration sets compressXml to true. draw.io opens both forms. Many older files use the compressed form, also most of the example files in §7.

In Python, with the standard library only:

import base64, urllib.parse, zlib

def decompress(text):
data = zlib.decompress(base64.b64decode(text), -15)
return urllib.parse.unquote(data.decode('utf-8'))

def compress(xml):
data = urllib.parse.quote(xml, safe="!'()*~").encode('ascii')
deflate = zlib.compressobj(9, zlib.DEFLATED, -15)
return base64.b64encode(deflate.compress(data) + deflate.flush()).decode('ascii')

To see the plain XML of a page in draw.io, select Extras > Edit Diagram. The online converter decodes and encodes compressed pages.

5. Diagrams in SVG and PNG images​

draw.io writes the diagram into an image when you save the file as an Editable Vector Image (.svg) or Editable Bitmap Image (.png), or export it with Include a copy of my diagram selected. draw.io opens such an image like a .drawio file.

5.1 .drawio.svg​

The root svg element has a content attribute with the whole draw.io file: the mxfile element, escaped as an attribute value. The rest of the SVG is the image of the diagram. To read the diagram, parse the value of content as XML. Its pages can be in the plain or the compressed form.

5.2 .drawio.png​

The draw.io file is in a text chunk before the first IDAT chunk of the PNG.

Written byChunkKeywordText
The draw.io editortEXtmxfileThe draw.io file, URL-encoded as by encodeURIComponent.
The command line of draw.io Desktop, with --embed-diagramzTXtmxGraphModelThe draw.io file, URL-encoded, then compressed with zlib.

draw.io reads both chunk types with both keywords. Some image hosting services remove text chunks from uploaded PNG images, and the diagram is lost.

In Python, with the standard library only:

import struct, urllib.parse, zlib

def read_png_diagram(path):
with open(path, 'rb') as f:
data = f.read()
pos = 8 # after the PNG signature
while pos + 8 <= len(data):
length, kind = struct.unpack('>I4s', data[pos:pos + 8])
body = data[pos + 8:pos + 8 + length]
if kind == b'IDAT':
break
if kind in (b'tEXt', b'zTXt'):
keyword, _, text = body.partition(b'\0')
if keyword in (b'mxfile', b'mxGraphModel'):
if kind == b'zTXt':
text = zlib.decompress(text[1:]) # after the compression method byte
return urllib.parse.unquote(text.decode('latin-1'))
pos += 12 + length
return None

6. XML Schema​

The XML Schema mxfile.xsd describes the plain form of a draw.io file: the elements of §2, their attributes and the types of the values.

URLContent
www.drawio.com/xsd/mxfile-1.0.xsdVersion 1.0. The file at this URL doesn't change. A new version gets a new URL.
www.drawio.com/mxfile.xsdThe newest version, currently 1.0.

Use the versioned URL to check against a fixed version.

  • Checked: the element hierarchy, the attributes of the elements in §2 and the types of their values. UserObject and object accept any attribute.
  • Not checked: the style strings, which are plain strings for the schema, see §2.7. That IDs are unique, and that parent, source and target refer to existing cells.
  • Rejected, although draw.io opens it: compressed pages, so decompress them first (§4). A file without mxfile. Attributes and elements that the schema doesn't list, such as vars on mxfile or the defs of style compression.

The schema is written to check generated files. To check a file with xmllint:

curl -O https://www.drawio.com/xsd/mxfile-1.0.xsd
xmllint --noout --schema mxfile-1.0.xsd diagram.drawio

The schema is maintained with the draw.io MCP server, in shared/mxfile.xsd of the drawio-mcp repository.

7. Example files​

FilesContentLicence
draw.io templatesThe templates of the draw.io editor, as .xml files, in the drawio repository.CC BY 4.0, and the licence section of the README
jgraph/drawio-diagramsExample diagrams and templates, as .drawio and .xml files.Apache License 2.0

Most of these files use the compressed form (§4). To open one in draw.io, select File > Open from > URL and enter its raw URL, for example https://raw.githubusercontent.com/jgraph/drawio-diagrams/dev/diagrams/schema.xml.