Skip to main content

​
Revisions

A revision describes a discrete editorial pass. Lives at the document root (revisions[]) or inside an element (element.revisions[]). 
{
  "id":       "<uuid>",
  "parent":   "<uuid>",
  "index":    3,
  "authors":  ["<uuid>"],
  "label":    "blue",
  "created":  "2026-01-14T10:12:00Z"
}
FieldTypeRequiredDescription
iduuid✓Revision identifier.
indexinteger ≥0✓Ordinal index within the parent revision chain.
authorsuuid[]✓At least one author id.
labelslug (3–30)✓Named label. Common values: draft, blue, pink, yellow, production-draft, final.
createddatetime✓ISO 8601.
parentuuid—Revision this was forked from.
metameta—Extension.

​
Status block

The industry revision status — lives under document.layout.status: 
{
  "color":   "blue",
  "round":   2,
  "updated": "2026-01-14T10:12:00Z"
}
color enum (industry-standard order): 
white · blue · pink · yellow · green · goldenrod · buff · salmon · cherry

​
Notes

Notes are annotations anchored to an element (or another note) via character index ranges. 
{
  "id":         "<uuid>",
  "parent":     "<uuid>",
  "highlight":  [[12, 27]],
  "contributor":"<uuid>",
  "created":    "2026-01-14T10:20:00Z",
  "text":       { "en": "Too on-the-nose." },
  "color":      "amber",
  "meta":       {}
}
FieldTypeRequiredDescription
iduuid✓Note identifier.
createddatetime✓ISO 8601.
texttext✓Language map.
parentuuid—Element (or note) the note is attached to.
highlight[[int, int], ...]—Array of [start, end] Unicode codepoint ranges within the rendered text of the parent element.
contributoruuid—Contributor who wrote the note.
colorslug—Reference to a colors[].id.
metameta—Extension.

​
Why UUIDs for notes

Anchored via parent: uuid and highlight ranges, notes survive rewrites of the surrounding element as long as the targeted stretch of text is still present. Renderers look up parent, find the element, and apply the highlight ranges to the rendered text.