# Scripts for Extracting Diagram Data in the Diagram-Design Repository

> Explore scripts in the cathrynlavery/diagram-design repo to extract diagram data. Parse draw.io XML and Mermaid text into a standardized internal format with Python.

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

---

**The cathrynlavery/diagram-design repository provides three dedicated Python scripts—[`drawio_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/drawio_extract.py), [`mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/mermaid_extract.py), and [`self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/self_check.py)—that parse draw.io XML and Mermaid text into a standardized internal diagram representation.**

The `cathrynlavery/diagram-design` project streamlines diagram manipulation by isolating format-specific parsing logic into dedicated utilities. These **scripts for extracting diagram data** reside in the `skills/diagram-design/scripts` directory and serve as the primary interface for converting external diagram formats into the repository's unified internal model.

## Core Extraction Scripts

The extraction layer consists of three specialized Python modules. Each script handles a specific aspect of the ingestion pipeline, from parsing proprietary XML formats to validating final data structures.

### drawio_extract.py for draw.io XML Processing

Located at [`skills/diagram-design/scripts/drawio_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/drawio_extract.py), this script handles **draw.io** (diagrams.net) files using Python's built-in `xml.etree.ElementTree` library. It extracts geometric shapes, connector paths, and metadata from the XML structure.

```python

# Example: Parsing a draw.io file programmatically

import sys
sys.path.insert(0, 'skills/diagram-design/scripts')
import drawio_extract

# Parse XML into internal representation

with open("architecture.drawio", "r") as f:
    xml_content = f.read()

diagram_model = drawio_extract.parse_xml(xml_content)
nodes = diagram_model["nodes"]
edges = diagram_model["edges"]

```

### mermaid_extract.py for Text-Based Diagrams

The [`skills/diagram-design/scripts/mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/mermaid_extract.py) module processes **Mermaid** markdown syntax. Unlike the XML approach, this script uses targeted string parsing to interpret flowchart and sequence diagram definitions embedded in markdown blocks.

```python

# Example: Extracting from Mermaid syntax

from skills.diagram_design.scripts import mermaid_extract

mermaid_code = """
graph TD;
    A[Start] --> B{Decision};
    B -->|Yes| C[Action 1];
    B -->|No| D[Action 2];
"""

diagram_data = mermaid_extract.parse_mermaid(mermaid_code)

```

### self_check.py for Data Validation

While not an extractor itself, [`skills/diagram-design/scripts/self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/self_check.py) provides critical **schema validation** for the output generated by the other two scripts. It ensures that parsed diagram data conforms to expected node and edge schemas before further processing occurs.

```python

# Example: Validating extracted diagram data

from skills.diagram_design.scripts import self_check

validation_result = self_check.validate_diagram(diagram_data)
if not validation_result.is_valid:
    print(f"Validation errors: {validation_result.errors}")

```

## The Four-Step Extraction Workflow

All **scripts for extracting diagram data** follow a standardized pipeline to ensure consistency across format types:

1. **Read** the source file, whether draw.io XML or Mermaid markdown text.
2. **Parse** the content using format-specific methods—`xml.etree.ElementTree` for draw.io, string tokenization for Mermaid.
3. **Transform** the parsed structure into a unified internal model containing nodes, edges, and attributes.
4. **Validate** the resulting model using [`self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/self_check.py) to guarantee schema compliance.

## Integration with Repository Commands

These extraction scripts power the high-level `import-drawio` and `import-mermaid` commands within the repository. By isolating parsing logic into standalone modules under `skills/diagram-design/scripts/`, the project maintains **separation of concerns** and allows direct script invocation from the command line.

```bash

# Command-line usage examples

python skills/diagram-design/scripts/drawio_extract.py input.drawio --output diagram.json
python skills/diagram-design/scripts/mermaid_extract.py diagram.md --validate

```

## Summary

- The **diagram-design** repository includes three primary **scripts for extracting diagram data**: [`drawio_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/drawio_extract.py), [`mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/mermaid_extract.py), and [`self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/self_check.py).
- **[`drawio_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/drawio_extract.py)** at [`skills/diagram-design/scripts/drawio_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/drawio_extract.py) handles XML parsing from draw.io files using `xml.etree.ElementTree`.
- **[`mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/mermaid_extract.py)** at [`skills/diagram-design/scripts/mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/mermaid_extract.py) processes text-based Mermaid diagram definitions through string parsing.
- **[`self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/self_check.py)** at [`skills/diagram-design/scripts/self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/self_check.py) validates extracted data against internal schemas to ensure data integrity.
- All scripts support both command-line execution and module import for integration with `import-drawio` and `import-mermaid` commands.

## Frequently Asked Questions

### What diagram formats does the diagram-design repository support?

The repository currently supports **draw.io** (XML-based) and **Mermaid** (text-based) formats through dedicated extraction scripts. The modular architecture located in `skills/diagram-design/scripts/` allows for straightforward addition of new format parsers.

### How does drawio_extract.py parse XML files?

The script utilizes Python's standard library `xml.etree.ElementTree` module to traverse the draw.io XML structure. It identifies shape elements and connector paths, extracting geometric data and metadata to populate the internal diagram model's nodes and edges according to the repository's unified schema.

### Can the extraction scripts be used as standalone tools?

Yes. While designed to support the repository's `import-drawio` and `import-mermaid` commands, each script functions independently. You can invoke them directly from the command line or import them as Python modules for use in external applications, as implemented in the `cathrynlavery/diagram-design` source code.

### What validation does self_check.py perform?

The [`self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/self_check.py) script verifies that extracted diagram data conforms to expected schemas, checking for required node attributes, valid edge connections, and data type consistency. This validation step ensures that downstream processing components receive properly structured diagram objects before further manipulation occurs.