An operation is the smallest thing a Change can say about a document: set this metadata key, replace this block, put these blocks here, delete those. A Change carries a list of them, and the daemon applies the list in order when it rebuilds the document.

This page defines the change/op union, the discriminated set of operations a Change body may contain. Its formal schema is attached as the schemaDefinition in this document's metadata, so the app can show it.

Every op is a map with a type string and, apart from that tag, only the fields its variant defines. An unknown field is a hard error, and the whole upload batch is rejected. Each variant mutates the document like this:

SetAttributes writes metadata by key path. Each key path is a last-writer-wins register. A newer op id overwrites, and setting a nested key removes an older value at its ancestor or descendant paths. block must be empty today, so this op only addresses document-level metadata.

ReplaceBlock sets the full state of one block: id, type, text, link, annotations and inline attributes. The newest replacement by op id wins. A block replaced but never positioned is a detached block.

MoveBlocks positions a contiguous run of sibling blocks under a parent (empty means the document root) after a reference position (empty means the start). Sibling order is a replicated growable array: concurrent inserts at the same reference are ordered by op id, and for a block moved several times the latest move wins. A move that would make a block its own ancestor is ignored.

DeleteBlocks moves blocks to the trash, which is itself a parent in the tree. A later move can bring a block back.

SetKey is the deprecated flat form of SetAttributes, still accepted for old Changes.

Op ids are (ts, idx, actor): the Change's timestamp, the op's position counter, and a number derived from the signer's principal. MoveBlocks.ref carries such an id as [ts, idx, actor], or as [idx] to mean an op earlier in the same Change. Inside a multi-block op the counter advances by the element's index, a quirk that is now part of the wire format. Documents has the full rules.

See also