Which visual/diagramming tools matter (draw.io, yEd, Mermaid, Excalidraw, Obsidian Canvas, Miro, Heptabase, Ellie.ai), what are their file formats, and which of their features can we generate or rebuild ourselves?
2026-07-31 · complete · confidence: medium
# The visual tool landscape — formats and buildability
Question: which visual tools matter for structured diagramming, what are their file formats, and — the point of asking — which of their features can we generate or rebuild ourselves?
The finding that organises everything else: the tools split cleanly by where the drawing lives. That single property predicts whether we can generate into it, read back from it, and whether the model stays ours.
| Tool | Format | Open? | Generate into it? | Read back? |
|---|---|---|---|---|
| Mermaid | text (its own DSL) | ✅ fully | trivial — it is text | ✅ parse the text |
| JSON Canvas (Obsidian) | .canvas — JSON, open spec 1.0 | ✅ published spec | ✅ trivial | ✅ trivial |
| Excalidraw | .excalidraw — JSON | ✅ documented | ✅ well-documented | ✅ |
| draw.io | .drawio / mxlibrary XML | ✅ documented | ✅ incl. shape libraries | ✅ (ADR-336, ADR-65) |
| PlantUML / Graphviz | text DSL | ✅ | trivial | ✅ |
| yEd | GraphML | ✅ standard | ✅ (published article) | ✅ |
| Archi | ArchiMate XML | ✅ standard | ✅ (ADR-86) | ✅ |
| Miro | REST API v2 | ⚠️ API only, OAuth | ✅ (ADR-342, implemented) | ✅ import back |
| Heptabase | closed | ❌ | ❌ | ❌ |
| Ellie.ai | closed platform | ❌ | ❌ (integrations only) | ❌ |
| PowerDesigner / Erwin | proprietary binary | ❌ | ❌ | ⚠️ with a parser |
The pattern: everything in the top half is a file we control. Everything in the bottom half is Gated Knowledge — legible only inside a licence or a login.
That is not a moral point, it is an architectural one. If the format is open, the diagram can be an output of the model. If it is closed, the diagram becomes a destination the model gets exported to and never returns from.
Format: a JSON object with type, version, source, an elements array, an appState object (grid, background), and a files object for embedded images. Every element shares identity/position/style fields; each type adds its own.
Unique feature worth naming: it looks hand-drawn. That is not a gimmick. A picture in a sketchy, imperfect style reads as provisional — it invites correction in a way a crisp generated ERD does not. Show a stakeholder a polished diagram and they assume it is decided; show them the same content in Excalidraw and they start editing.
That makes it the right output for proposals, and the wrong one for records.
Generation: documented and practical. Excalidraw ships restoreElements / restoreAppState, which fill in defaults and repair minor schema gaps — so a generator can emit structurally-correct-but-incomplete JSON and let the library normalise it. Meaningfully lowers the cost of writing one.
Export with the scene embedded: PNG and SVG can carry the original scene data inside the file. An exported image is still editable — no separate source file to lose. For documentation and websites this is close to ideal: ship one asset, and it remains the source.
Also: mermaid-to-excalidraw exists officially. Mermaid text → editable hand-drawn scene, no bespoke generator required. That is the cheapest possible route from model to sketch.
Format: .canvas, two top-level arrays — nodes and edges — under JSON Canvas spec 1.0. Node types: file (references a vault file, optionally a section), text (markdown), link (a URL), group. Required: id, type, x, y, width, height. Edges connect via fromNode/toNode with fromSide/toSide. Array order is z-index. Colours use a dual system: preset identifiers plus custom values, with hex values deliberately left to the application.
Why this is the most interesting entry in the table. It is an open standard for infinite canvases, published by Obsidian, with Python implementations already on PyPI. Not a vendor format that happens to be readable — a spec written to be implemented by others.
And the killer property for us: file nodes reference vault files. A canvas is not a picture of notes, it is a spatial arrangement of the notes themselves. Move a note, the canvas still points at it. Edit the note, the canvas shows the change. The picture and the content are the same objects — which is the Living Diagrams argument arriving from the note-taking world instead of the data world.
This is also the closest existing thing to what the Beacon board already does with board.yaml. ⚠️ Worth considering: adopt JSON Canvas as the board format instead of a bespoke YAML shape. Same idea, published spec, existing tooling, and the boards become openable in Obsidian.
Already curated (rel 3 / qual 3 / follow passive). Visual-first PKM: whiteboards plus cards, mindmaps, whiteboard journals, PDF parsing, and since 2025 an AI layer (chat-with-whiteboard, MCP server).
What to steal, conceptually:
links graph.What not to copy: it is a closed tool. The visual model is worth studying; the architecture is the opposite of ours.
The buildable list, cheapest first:
| Build | Effort | Why | |
|---|---|---|---|
| Mermaid generation | trivial | text out of a model; already done in places (ADR-131) | |
| JSON Canvas generation | low | two arrays; open spec; Python libs exist | |
| Excalidraw generation | low-medium | documented JSON; restoreElements forgives gaps; or route via mermaid-to-excalidraw | |
draw.io palettes (mxlibrary) | low | XML + JSON array; the [[concept-generated-palettes | Generated Palettes]] mechanism |
| Adopt JSON Canvas in our board | medium | replaces bespoke board.yaml; buys Obsidian compatibility | |
| Card-is-the-unit, board-is-a-view | medium | Heptabase's model, already half-present in the board's library rail | |
| Board-as-AI-context | medium | "answer only from this board" — our links graph makes it feasible | |
| Real-time multi-user canvas | high | competing with Ellie/Miro on their ground. Probably not. |
The honest boundary: everything up to board-as-AI-context is a weekend-to-fortnight of work each and compounds with what exists. Real-time collaboration is a different product, and the sensible answer there is to borrow Miro rather than rebuild it.
1. Openness of format is the dividing line. Open format → the diagram becomes an output of the model. Closed → the diagram becomes a place the model goes to die.
2. JSON Canvas is the sleeper. An open spec for infinite canvases, with file nodes pointing at real notes. Strong candidate to replace the bespoke board.yaml.
3. Excalidraw's hand-drawn look is a feature, not styling. It signals provisional, which changes how people respond. Right for proposals, wrong for records.
4. Scene-embedded PNG/SVG solves the documentation problem. One asset that is also the source.
5. mermaid-to-excalidraw is the cheapest model→sketch path and already exists officially.
6. Heptabase gives the conceptual model (card = unit, board = view, board = AI context) without giving an architecture worth copying.
7. Do not build real-time collaboration. Borrow Miro for the moments that need a room.
.canvas from the links table — does Obsidian open it cleanly?board.yaml → JSON Canvas?mermaid-to-excalidraw on a real generated ERD; is the output presentable?PyJSONCanvas, openjsoncanvasW:/systems/curated-sources/heptabase/2026-07-31_miro-api-collaborative-visual-experience.md