Changes as JSON Patch

Structured changes to a document’s JSON data travel as JSON Patch (RFC 6902) — ordered lists of add, remove, replace, move, copy, and test operations. Patches are compact, human- and agent-readable, and double as the document’s audit trail in the event log.

Heads up

We’ve hit real problems applying RFC 6902 in a collaborative setting — array addressing chief among them. The workarounds are baked into the design (ordered records instead of arrays, guards instead of blind patches), and the issues are written up in JSON Patch RFC issues.

Guards

A patch that was computed against one version of a document may not be safe to apply to a newer version. Writers choose how strict to be, per update:

• Sequence guard — “apply only if the document is still at sequence N.” The strictest mode: any concurrent change rejects the write.
• Patch guard — the patch carries RFC 6902 test operations asserting the values it’s about to change. Concurrent changes to other parts of the document are tolerated; a failed test rejects the write.

When generating a patch by diffing, test operations are emitted automatically for replace and remove operations, so the patch defends itself by construction.

A rejected guard is a benign signal, not an error: the optimistic entry is dropped, the client sees the winning state, and the caller can re-derive and retry. The session client builds its conflict detection on the same primitive.

Why patches — not CRDT operations, not domain events?

For structured data, datadata deliberately uses server-ordered patches with guards rather than CRDTs — and rather than an application-defined event vocabulary with reducers: a patch is self-applying data, so history can be read and replayed in any context without the application’s code. The trade-offs of both choices are discussed in Design decisions. For collaborative text, where convergence-per-keystroke matters, it uses Yjs instead. The two travel together in the same update.