drawspec

drawspec

Diagrams from a JSON description — no coordinates, so nothing to misplace. You say what the diagram *means*: the boxes, the arrows, the labels, and a role for each. drawspec decides every position, size, route and colour, and draws a clean SVG, PNG or plain-text diagram.

It is built for language models first. An LLM that writes SVG by hand gets the content right and the placement wrong — arrows that miss their boxes, text that spills out, lines that stop short. A drawspec document has no x, y or font size to get wrong: those fields are refused, and every mistake comes back as an error pointing at the exact field, so the model can fix it and try again.

pip install drawspec

drawspec render diagram.json -o diagram.svg

[Browse the gallery: more than 30 kinds, drawn →](https://nuncaeslupus.github.io/drawspec/docs/gallery/)

Example

You write this:

{

"$schema": "https://nuncaeslupus.github.io/drawspec/schema/drawspec-v1.schema.json", "version": 1, "kind": "flow", "title": "The nightly import", "description": "The vendor's export is fetched, checked and loaded into staging before it replaces the live table; a timeout and a deadlock are each retried in place.", "nodes": [ {"id": "fetch", "text": "Fetch the vendor's export", "role": "start"}, {"id": "check", "text": "Do the row counts match?", "role": "decision"}, {"id": "load", "text": "Load into staging"}, {"id": "page", "text": "Page the data owner", "role": "terminal"}, {"id": "swap", "text": "Swap staging into live", "role": "terminal"} ], "edges": [ {"from": "fetch", "to": "fetch", "label": "timed out: retry"}, {"from": "fetch", "to": "check"}, {"from": "check", "to": "load", "label": "yes"}, {"from": "check", "to": "page", "label": "no"}, {"from": "load", "to": "load", "label": "deadlock: retry"}, {"from": "load", "to": "swap"} ] }

drawspec draws this:

The same document as text, for a terminal, a commit message or a code block (--format text --charset ascii):

             *---------------------------*

| Fetch the vendor's export +-+ timed out: retry | |<+ *-------------+-------------* | v +--------------------------+ < Do the row counts match? > ++-------------------+-----+ | yes | no +----+ | v v +-------------------+ .---------------------. | Load into staging +-+ deadlock: retry ( Page the data owner ) | |<+ '---------------------' +---------+---------+ | v .------------------------. ( Swap staging into live ) '------------------------'

A sequence diagram works the same way — participants and messages in order; activation bars, arrows and spacing are worked out for you:

{

"version": 1, "kind": "sequence", "title": "Resolving a name the first time", "caption": "Nothing is cached yet, so the resolver walks the hierarchy from the top.", "participants": [ {"id": "laptop", "text": "Laptop"}, {"id": "resolver", "text": "Recursive resolver", "role": "emphasis"}, {"id": "root", "text": "Root server"}, {"id": "tld", "text": ".org server"}, {"id": "auth", "text": "Authoritative server"} ], "messages": [ {"from": "laptop", "to": "resolver", "text": "where is wiki.example.org?"}, {"from": "resolver", "to": "root", "text": "where is wiki.example.org?"}, {"from": "root", "to": "resolver", "text": "ask the .org servers", "role": "weak"}, {"from": "resolver", "to": "tld", "text": "where is wiki.example.org?"}, {"from": "tld", "to": "resolver", "text": "ask ns1.example.org", "role": "weak"}, {"from": "resolver", "to": "auth", "text": "where is wiki.example.org?"}, {"from": "auth", "to": "resolver", "text": "203.0.113.7", "role": "weak"}, {"from": "resolver", "to": "resolver", "text": "cache it for the TTL", "note": "the next lookup stops here"}, {"from": "resolver", "to": "laptop", "text": "203.0.113.7", "role": "weak"} ] }

More than 30 kinds of diagram

Flow charts, sequence diagrams, state machines, ER and class diagrams, Gantt charts, swimlanes, mind maps, timelines, Venn, Sankey, treemaps, pie and bar charts, kanban boards, fishbone, family trees, file trees, timing diagrams, network diagrams, tournament brackets, cladograms and more — one format for all of them. Click a drawing to open it full size, or a kind's name for its source — the code is all here.

sequence entities states

gantt mindmap sankey

venn chart fishbone

<img src="https://raw.githubusercontent.com/nuncaeslupus/drawspec/main/doc