drawspec

Get the smallest valid document of one kind, as JSON ready to edit: the fastest way to the right field names. `kind` is one exact value from `list_kinds`, e.g. `flow`. Use it after `list_kinds` has settled the kind, and `get_schema` only for a field the example leaves out. Static and local: the document `drawspec example <kind>` prints, under 1 KB, identical every call; it passes `validate_document` as is. An unknown kind is an error result naming `list_kinds`.

Get the JSON Schema (draft 2020-12) for one kind's documents: every field it accepts, with types, limits and descriptions, plus only the shared `$defs` it refers to. `kind` is one value from `list_kinds`, e.g. `sequence`. Use it when `get_example` does not show a field you need. Local and deterministic: 3 to 13 KB per kind, cut from the ~150 KB published schema. Referential rules (unique ids, edges that land on real nodes) are beyond JSON Schema — `validate_document` checks those.

List the vocabulary: all 36 values `kind` may take, each with a one-line purpose. Call it first, before choosing a kind — several kinds are not box-and-arrow diagrams and are easy to miss — then `get_example` for a starting document. No arguments. Static and local: no I/O, about 4 KB, the same answer every call, in a fixed order that keeps related kinds (graphs, grids, shapes, charts) adjacent.

Draw the document. Use it when it is ready to show; while still fixing errors, `validate_document` returns just the verdict. Returns one content block by `format`: `svg` (default) self-contained SVG text, safe inline in Markdown; `png` a base64 `image/png` block (needs the server's `drawspec[png]` extra, slowest); `text` plain text for a code block, only for kinds with a text form. `width`/`height` override the document's size; with `text`, `width` is cells per line and `height` and `theme` are ignored. Local, deterministic, writes nothing. Refusals are error results with JSON text `{"ok": false, "error": "DocumentError", "message": "...", "violations": [{"pointer": "/edges/0/to", "message": "..."}]}`: `error` is e.g. `DocumentError` or `FitError`, `pointer` is RFC 6901 (empty for the whole document), and `violations` is never empty.

Check whether `render_document` would refuse this document, and exactly where. It renders with the same `theme` and discards the drawing, so it passes only what draws; every violation comes back at once, so one pass is one edit. Call it while writing or editing; skip it when about to render anyway, since `render_document` refuses in the same shape. Local, deterministic, milliseconds. Refusals are error results with JSON text `{"ok": false, "error": "DocumentError", "message": "...", "violations": [{"pointer": "/edges/0/to", "message": "..."}]}`: `error` is e.g. `DocumentError` or `FitError`, `pointer` is RFC 6901 (empty for the whole document), and `violations` is never empty.