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 name | Content |
|---|---|
.drawio | The XML document described on this page. Media type application/vnd.jgraph.mxfile. |
.drawio.svg | An SVG image of the diagram that contains the XML document, §5.1. |
.drawio.png | A PNG image of the diagram that contains the XML document, §5.2. |
.xml | The 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
| Attribute | Description |
|---|---|
host | Where the file was last saved, for example app.diagrams.net, or Electron for draw.io Desktop. |
pages | Number of pages, written for files with more than one page. |
compressed | true if draw.io saves the pages of this file in the compressed form (§4), false if not. Set with File > Properties > Compressed. |
vars | File 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
| Attribute | Description |
|---|---|
id | Page ID, unique in the file. |
name | Page 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.
| Attribute | Description |
|---|---|
dx, dy | Scroll position when the file was saved. |
grid, gridSize | Grid on or off, and the grid size in px. |
page, pageScale, pageWidth, pageHeight | Page view on or off, page scale, and page size in px. 850 × 1100 is US Letter. |
background | Page colour, for example #ffffff, or none. |
shadow | Shadow on all shapes. |
math | Mathematical typesetting in labels. |
adaptiveColors | Colours in dark mode: auto, simple or none. |
guides, tooltips, connect, arrows, fold | Editor 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.
| Attribute | Description |
|---|---|
id | Cell ID, unique in the page. Any string. |
parent | ID of the parent cell. |
value | The label. HTML if the style contains html=1, escaped as XML in the attribute: <b>Bold</b>. |
style | The style, §2.7. |
vertex | 1 for shapes, including text, groups and containers. |
edge | 1 for connectors. |
source, target | IDs of the cells that the ends of a connector are connected to. |
connectable | 0 if connectors can't be connected to the cell. |
collapsed | 1 if a container is collapsed. |
visible | 0 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.
| Attribute | Description |
|---|---|
x, y | Position of the top-left corner. |
width, height | Size. |
relative | 1 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. |
as | Always geometry. |
| Child element | Description |
|---|---|
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>
| Attribute | Description |
|---|---|
label | The label. |
tooltip | Tooltip text. |
link | Link that opens when the cell is clicked. |
tags | Tags, separated by spaces. |
placeholders | 1 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 exampleellipseortext. - Keys and values are case-sensitive.
1is on,0is off. Colours are#rrggbbornone. - 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.
- URL-encode the XML as JavaScript's
encodeURIComponentdoes. - Compress the result with raw DEFLATE (RFC 1951, without a zlib header or checksum).
- 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 by | Chunk | Keyword | Text |
|---|---|---|---|
| The draw.io editor | tEXt | mxfile | The draw.io file, URL-encoded as by encodeURIComponent. |
The command line of draw.io Desktop, with --embed-diagram | zTXt | mxGraphModel | The 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.
| URL | Content |
|---|---|
| www.drawio.com/xsd/mxfile-1.0.xsd | Version 1.0. The file at this URL doesn't change. A new version gets a new URL. |
| www.drawio.com/mxfile.xsd | The 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.
UserObjectandobjectaccept any attribute. - Not checked: the style strings, which are plain strings for the schema, see §2.7. That IDs are unique, and that
parent,sourceandtargetrefer 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 asvarsonmxfileor thedefsof 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
| Files | Content | Licence |
|---|---|---|
| draw.io templates | The 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-diagrams | Example 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.
Related
- Style reference: all style keys and values.
- XML generation reference: rules for generated XML, such as connectors, containers, layers, metadata and dark mode.
- Generate and validate draw.io diagrams with AI
- Style compression
- File format for custom shape libraries
- Edit the XML source of a diagram
- Save a diagram in various formats
- Embedded XML in PNG image files
- Encode a diagram in a URL