Edit Operations Reference

Operations

A few rules hold for every operation:

• Kinds. add and insert take a shape kind (square, circle, diamond, cylinder, stadium, hexagon and the rest) or text, sticky, table, annotation or link-card. A shape kind it does not know is turned into the nearest one, with a shape_coerced warning. Arrows are made with connect; images, videos and drawn strokes are not made by name, but an add in the JSON form can carry a whole element ({ "op": "add", "element": { … } }), which is how an uploaded image goes on a tab.
• Ids. id= names a new element so later operations in the same changeset can use it. It is a short slug: a lowercase letter, then up to 23 lowercase letters, digits, - or _. Without one, the element takes the slug of its label (or of its kind, as arrow, arrow-2).
• Fields. label, note, shape, fill, stroke, text-color, border, text (a size: sm, md, lg or scale), font and line (straight, angled or curved) work on the kinds that have them, beside any stored field of the element. fill= takes a colour slot of the tab's theme by name (such as theme), which follows a theme change; a hex colour works too, with a colour_overrides_theme warning. A sticky takes its own colour names instead. A number, true or false is read as JSON, and a value starting with [ or { is read as JSON as written.
• Comments are not fields. Comment threads, votes and ideas travel live between people, so edit operations never change them; comments have their own endpoints.
• Locks. A changeset on a locked tab, or one that would change a locked element or an element on a locked layer, is refused with element_locked.

Placement

add and move take one placement; insert places itself on its arrow.

Without a placement, a new element goes beside the last one added, or to the right of everything. A spot already taken moves along the placement's direction until it is free. In the JSON form a placement is { "rel": "below", "ref": "n2", "gap": 40 } or { "rel": "at", "x": 0, "y": 200 }, and by=dx,dy is "by": [dx, dy].

What you did not ask to change stays put. set moves nothing except a box that grows around its centre to fit a longer label (reported). Only layout and a whole-tab replace lay out many elements, and only the ones they name.

The Answer

A changeset answers with one line per element, the same for a dry run (?dryRun=1, or --dry-run on the CLI) and a write:

~ n3  label "Login"→"Sign in" · shape square→stadium · widened 140→160
+ verify  square "Verify email" @45,300 131×120
~ a3  to n4→verify
+ arrow  verify→n4 (style of a3)
» n4 n5 n6  +0,+160 (make room)
f2  +verify
rev 41→42 · cs_8k2m4q7d1x · lint clean · revert: livediagram changeset revert 3f9c2a71-… cs_8k2m4q7d1x

The last line carries the tab's new revision, the changeset's id, the lint verdict and the command that reverts it. A changeset that changes nothing answers nothing changed.

Warnings do not stop a changeset: shape_coerced (an unknown shape kind became a known one), value_coerced, label_capped (a shape's label over 40 characters kept its heading and moved the full text into the note), colour_overrides_theme, arrows_freed (from keep-arrows), and no_base (sent without a base revision).

Lint Findings

Every changeset lints the whole tab it leaves behind, and GET /documents/{id}/tabs/{tabId}?view=lint (or livediagram tab lint) lists the findings, each ending with a fix you can send as a changeset:

5 crossings · 2 behind · 0 overlaps · 1317×1196 → 3 warnings, 6 info
W arrow-behind-box   orders→bus passes behind pay  fix: set orders->bus line=angled

Boxes no arrow connects count as decoration and may overlap; the group checks judge frames, not lanes. Above 300 arrows the crossing check is skipped (the summary says so) and every other check still runs. The verdict on a changeset's last line reads lint clean or, say, lint 2 warnings, 1 info.