Edit decks with JSON Patch
Change a deck with a short, checkable list of operations instead of rewriting the file.
In this example, you’ll change a subtitle from Draft to Board review, add an item and then restore the original deck. Start with the two-slide example.
What JSON Patch is
JSON Patch is an existing IETF standard, RFC 6902. OPF did not invent it. A patch is a JSON array of operations. Each operation names one place in a JSON document with a path, such as /slides/0/title, and says what to do there: add, remove, replace, move, copy, or test that a value is what you expect.
An OPF deck is a JSON document, so a patch can describe a change to it exactly. That is why OPF uses JSON Patch for edits: a patch is small and precise, and a person can review it before it runs. An agent or a tool can propose one without rewriting the whole file. opf edit applies a patch whole or not at all, then checks the result.
Example: edit a deck
Install the CLI:
npm install -g @openpresentation/cli@0.34.2Save a small deck as deck.opf.json. Both slides have an id:
{
"$schema": "https://openpresentation.org/schema/opf/v1",
"name": "Q3 planning",
"slides": [
{ "id": "intro", "layout": "cover", "title": "Q3 planning", "subtitle": "Draft" },
{ "id": "goals", "layout": "list", "title": "Goals", "items": ["Ship the beta", "Hire two engineers"] }
]
}Save this patch as changes.json. The first operation is a test guard: if the cover's subtitle is no longer "Draft", the edit fails and nothing changes. The paths name slides by id (@intro, @goals) rather than by position, and - adds after the last list item.
[
{ "op": "test", "path": "/slides/@intro/subtitle", "value": "Draft" },
{ "op": "replace", "path": "/slides/@intro/subtitle", "value": "Board review" },
{ "op": "add", "path": "/slides/@goals/items/-", "value": "Open the Berlin office" }
]Apply it:
opf edit deck.opf.json --patch changes.jsonThe command exits 0. With no output file, the edited deck goes to stdout and the report goes to stderr:
{
"$schema": "https://openpresentation.org/schema/opf/v1",
"name": "Q3 planning",
"slides": [
{
"id": "intro",
"layout": "cover",
"title": "Q3 planning",
"subtitle": "Board review"
},
{
"id": "goals",
"layout": "list",
"title": "Goals",
"items": [
"Ship the beta",
"Hire two engineers",
"Open the Berlin office"
]
}
]
}{
"command": "edit",
"ok": true,
"input": {
"file": "/private/tmp/patch-demo/deck.opf.json",
"sha256": "d98b09e21469302695ef409d953dd51f85b7bb0652b104944be62f4b550debcf",
"bytes": 301
},
"outputs": [
{
"file": "-",
"sha256": "52689182276a41249efb5f387a36161576c58387b1d074a9f82fd46afc645db6",
"bytes": 422,
"mediaType": "application/json"
}
],
"findings": [],
"counts": {
"error": 0,
"warning": 0,
"info": 0
},
"inverse": [
{
"op": "remove",
"path": "/slides/1/items/2"
},
{
"op": "replace",
"path": "/slides/0/subtitle",
"value": "Draft"
}
]
}inverse is the patch that undoes the edit. Add an output file name to write the deck to a file, or use -i to rewrite the input in place.
Review and undo
Write the result to a file and compare it with the original:
opf edit deck.opf.json --patch changes.json next.opf.json
opf diff deck.opf.json next.opf.json2 changes (slides: 2 modified)
Slides
~ slide #1 "Q3 planning" (id intro)
~ subtitle "Draft" -> "Board review"
~ slide #2 "Goals" (id goals)
+ items[2] "Open the Berlin office"To undo, save the report's inverse as undo.json and apply it:
[
{ "op": "remove", "path": "/slides/1/items/2" },
{ "op": "replace", "path": "/slides/0/subtitle", "value": "Draft" }
]opf edit next.opf.json --patch undo.json restored.opf.json
opf diff deck.opf.json restored.opf.json --exit-codeNo differences.Every command above exits 0. The report's input.file is the absolute path of your deck. Run changes.json a second time, against next.opf.json, and the test guard stops it: nothing is applied (see Errors).
Reference
A short summary. The full detail is in Patch, diff, merge and format.
Operations and paths
- All six RFC 6902 operations:
add,remove,replace,move,copy,test. An unknownopis an error; unknown members of an operation are ignored. - A patch applies whole or not at all. Only the final document is checked, so a patch may pass through an invalid state on the way.
- Paths are strict RFC 6901 JSON Pointers.
-is accepted only as the final token of anadd, or of amoveorcopytarget. Array indexes are plain decimals:01,-1and1.0are errors. testfails on a missing path and compares JSON values: member order does not matter, array order does.
Id-addressed paths
Indexes move when a slide is inserted above another. Slides and content payloads can carry an optional id, and in an array the token @intro is the element whose id is intro: /slides/@kpis/blocks/@note/text. It is still a valid JSON Pointer. An id that begins with @ is written @@id. An id that no element has is an error, and so is an id that several elements share. As the last token of add, copy or move, an id inserts before that element.
Only if nothing changed: expectHash
In the library, documentHash(doc) is a SHA-256 over the document's canonical JSON, so key order and formatting do not change it. Pass it as expectHash and the patch applies only to that exact document; otherwise it fails with patch-hash-mismatch and nothing is applied. In the CLI, --expect-sha256 is a different check: the digest of the file's bytes (the report's input.sha256), used with -i. A file that no longer has that digest is not rewritten, and the CLI exits 1 with the code hash-mismatch.
import { applyPatch, applyPatchWithInverse, documentHash } from "@openpresentation/opf/patch"
const hash = documentHash(deck) // "sha256:" + 64 hex digits
const next = applyPatch(deck, patch, { expectHash: hash }) // nothing is applied if deck is not the document hashed
const { presentation: after, inverse } = applyPatchWithInverse(deck, patch)
applyPatch(after, inverse) // deep-equals deckInverse patches and undo
applyPatchWithInverse and invertPatch return operations that restore the input exactly, in reverse order, with concrete array indexes rather than ids. test has no inverse. opf edit reports the same patch as inverse, and the editor keeps these patches as its undo stack.
Diff, merge and format
opf diff <a> <b> [--format text|json|patch] [--exit-code]matches slides and other array elements byid, then by content, and finds moves.--format patchprints a patch you can pass toopf edit --patch. It exits 0, or 1 with--exit-codewhen the decks differ; usage and I/O errors exit 2.opf merge <base> <ours> <theirs> [output]is a three-way merge. Conflicts are never silent: without--prefer ours|theirs, a conflict writes nothing, reports the conflicts on stderr and exits 1; with it, the chosen side is written and every conflict is still reported. The merged deck is checked before it is written.opf formatwrites canonical key order and layout without changing any value.--checkexits 1 if a file would change;-irewrites changed files.
Errors
A patch that fails is an OPFPatchError with a stable code, the failing operation's index and path, and a message that starts with Operation <n>:. A failed test is patch-test-failed. Other codes include patch-path-missing, invalid-json-pointer, patch-id-not-found, patch-id-ambiguous and patch-hash-mismatch; the reference lists all of them.
Compatibility
CLI 0.9.2 already has opf edit; opf diff, opf merge and opf format are in CLI 0.10.0 and later. The library entrypoints (@openpresentation/opf/patch, /diff, /format) are in core 0.12.0 and later. opf diff --format json has its current report shape from CLI 0.18. Run opf --help to check your install. The example on this page was checked on November 12, 2026 with CLI 0.27.0 and 0.34.2, which gave the output shown.