# How to Import draw.io Diagrams into the Diagram Design Tool: A Complete Technical Guide

> Learn to import draw.io diagrams into Diagram Design with our technical guide. Our script securely normalizes XML for structured representation. Explore the process now.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: how-to-guide
- Published: 2026-09-08

---

**The Diagram Design tool imports draw.io diagrams by executing the [`drawio_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/drawio_extract.py) script, which deterministically normalizes raw draw.io XML into a structured intermediate representation through a secure, three-pass parsing pipeline.**

Importing draw.io diagrams into the **Diagram Design tool** requires understanding the deterministic extraction pipeline that transforms proprietary draw.io formats into a normalized intermediate representation. This guide explains the complete technical flow implemented in the `cathrynlavery/diagram-design` repository, from secure payload extraction to the final Markdown digest generation that drives the rendering pipeline.

## Supported draw.io File Formats

The extractor in [`skills/diagram-design/scripts/drawio_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/drawio_extract.py) accepts multiple draw.io variants to maximize compatibility. You can import diagrams using the following extensions:

- **`.drawio`** – Standard uncompressed XML format
- **`.xml`** – Raw XML exports from draw.io
- **`.drawio.png`** – PNG images with embedded draw.io XML metadata
- **`.drawio.svg`** – SVG files containing embedded diagram data

The script handles three distinct payload types: raw XML strings, compressed base‑64 encoded payloads, and XML embedded within image chunks. This multi-format support ensures that whether you export directly from the draw.io editor or save diagrams as images, the Diagram Design tool can extract the underlying structure.

## The Extraction Pipeline in drawio_extract.py

The import process follows a deterministic pipeline that never makes design decisions—it only normalizes data. The core extractor implements security checks and multi-pass parsing to build a complete intermediate representation (IR).

### Secure Payload Handling

Before parsing XML, the extractor determines how to extract the raw payload based on file headers:

- **`_png_embedded_xml`** – When the file starts with the PNG magic header, this function pulls the `mxfile` chunk from the PNG metadata.
- **`_svg_embedded_xml`** – For SVG files, it extracts the `mxfile` or `mxGraphModel` from a `content=` attribute within the SVG markup.
- **`_inflate`** – For compressed files, it decodes base‑64 and deflates the payload to reveal the underlying XML.
- **`MAX_XML_BYTES`** – All decompression respects a hard size limit to prevent resource-exhaustion attacks on the parsing stage.

### XML Validation and Security

After extraction, the script validates the XML using **`_reject_unsafe_xml`**, which scans for DTD declarations and ENTITY tags to prevent XML external entity (XXE) attacks. The parser then uses `xml.etree.ElementTree` to parse the `<mxfile>` or bare `<mxGraphModel>` root element into a traversable DOM structure.

### Three-Pass IR Construction

The parser walks the `mxGraphModel` in three sequential passes to build the IR:

- **Pass 1** gathers raw cells, handling `<object>` and `<UserObject>` containers that group visual elements.
- **Pass 2** creates `Node` objects for vertices, resolves absolute geometry coordinates, and builds a parent/child hierarchy to preserve diagram structure.
- **Pass 3** creates `Edge` objects for connections, folds edge‑label vertices into the edge’s label property, and calculates node degrees (in/out counts) for topology analysis.

This three-pass approach ensures that all geometric relationships and connection metadata are fully resolved before the analysis phase begins.

## Structural Analysis and Type Inference

Once the IR is constructed, the **`analyze(page)`** function computes structural signals that drive downstream design decisions. This analysis extracts:

- Node and edge counts
- Shape families (rectangles, circles, specific icon sets)
- Cycle detection and hub identification (high-degree nodes)
- Entry points and disconnected components
- **Type candidates** such as "flowchart," "architecture," or "tree"

These signals are crucial because the Diagram Design tool uses them during the "type inference" step to apply appropriate visual styles and layouts when rendering the final diagram according to [`output-spec.md`](https://github.com/cathrynlavery/diagram-design/blob/main/output-spec.md).

## How to Import: Three Methods

The repository provides three interfaces for importing draw.io files, ranging from CLI scripting to integrated slash commands.

### Method 1: Command Line Interface

For automation and debugging, run the extractor directly:

```bash

# Basic CLI usage – extracts a digest from a draw.io file

python3 skills/diagram-design/scripts/drawio_extract.py my-diagram.drawio

# Get the full IR as JSON (useful for debugging)

python3 skills/diagram-design/scripts/drawio_extract.py my-diagram.drawio --json

```

### Method 2: Programmatic Python API

For custom integrations, import the extractor functions directly:

```python
from pathlib import Path
from skills.diagram-design.scripts.drawio_extract import parse_file, digest

path = Path("my-diagram.drawio")
pages = parse_file(path)                 # returns a list of Page objects

selected = pages[:1]                     # usually the first page

markdown = digest(path, pages, selected, max_rows=40)
print(markdown)

```

The `parse_file` function returns a list of `Page` objects, while `digest` generates a human-readable Markdown summary of the selected pages.

### Method 3: Slash Command Integration

For end-users within the Diagram Design skill UI, the **`import-drawio`** slash command orchestrates the full pipeline:

```bash
import-drawio my-diagram.drawio --format=svg --size=slide-16x9 --detail=balanced

```

This command, defined in [`commands/import-drawio.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/import-drawio.md), supports extensive customization:

- **`--format`** – Output format: `html`, `svg`, `png`, or `html+png`
- **`--size`** – Target dimensions (e.g., `slide-16x9`)
- **`--detail`** – Rendering fidelity: `faithful`, `balanced`, or `simplified`
- **`--audience`** – Target reader: `engineer`, `mixed`, or `executive`
- **`--type`** – Force a specific diagram type classification
- **`--page`** – Select specific pages by number, name, or `all`
- **`--variant`** – Color scheme: `light`, `dark`, or `full`
- **`--output`** – Custom output path

The command invokes the extractor, verifies the exit code is zero, confirms the digest contains nodes, and then generates the final editorial diagram according to the [`output-spec.md`](https://github.com/cathrynlavery/diagram-design/blob/main/output-spec.md) configuration.

## Key Files in the Import Architecture

Understanding the repository structure helps when debugging or extending import functionality:

- **[`skills/diagram-design/scripts/drawio_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/drawio_extract.py)** – Core extractor that normalizes draw.io input into an IR and produces Markdown or JSON digests.
- **[`scripts/verify-drawio-import.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-drawio-import.py)** – Test harness that validates the entire import pipeline against known fixtures, checking payload handling, geometry resolution, and shape classification.
- **[`commands/import-drawio.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/import-drawio.md)** – Slash-command definition that orchestrates the extractor and rendering steps for end-users.
- **[`skills/diagram-design/references/import-drawio.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/import-drawio.md)** – Human-readable reference explaining required behavior and defaults used by the command.
- **[`skills/diagram-design/references/output-spec.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/output-spec.md)** – Specification of final diagram formats, sizes, and detail levels rendered after extraction.
- **[`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md)** – Central skill documentation defining diagram types, taste gates, and visual style guidelines applied post-import.

## Summary

- **Deterministic extraction** – The [`drawio_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/drawio_extract.py) script never makes design decisions; it only normalizes raw draw.io data into a structured intermediate representation.
- **Multi-format support** – Handles `.drawio`, `.xml`, `.drawio.png`, and `.drawio.svg` files through specialized payload extraction functions.
- **Security-first parsing** – Implements `MAX_XML_BYTES` limits and `_reject_unsafe_xml` validation to prevent resource exhaustion and XXE attacks.
- **Three-pass normalization** – Builds the IR by first gathering cells, then resolving geometry and hierarchies, and finally processing edges and labels.
- **Flexible integration** – Supports direct CLI usage, Python API integration, and slash-command orchestration within the Diagram Design skill.

## Frequently Asked Questions

### What file formats can I import into the Diagram Design tool?

The tool accepts `.drawio`, `.xml`, `.drawio.png`, and `.drawio.svg` files. The extractor handles raw XML, compressed base‑64 payloads, and XML embedded within PNG or SVG image chunks, ensuring compatibility with any standard draw.io export method.

### How does the tool handle compressed or embedded draw.io files?

The extractor detects file types by magic headers. For PNG files, it uses `_png_embedded_xml` to extract the `mxfile` chunk; for SVG files, `_svg_embedded_xml` pulls data from the `content=` attribute; for compressed XML, `_inflate` decodes base‑64 and decompresses the payload, respecting `MAX_XML_BYTES` limits to prevent memory exhaustion.

### Can I import specific pages from multi-page draw.io diagrams?

Yes. When using the slash command, specify the `--page` flag with a page number, name, or `all` to import multiple pages. In the Python API, `parse_file` returns a list of `Page` objects, allowing you to slice or select specific indices (e.g., `pages[:1]` for the first page) before calling `digest`.

### Is the import process secure against malicious files?

The implementation includes multiple security layers: `_reject_unsafe_xml` blocks DTD and ENTITY declarations to prevent XXE attacks, while `MAX_XML_BYTES` limits prevent decompression bombs from exhausting system resources. The [`scripts/verify-drawio-import.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-drawio-import.py) test harness continuously validates these protections against malicious fixtures.