OPF

Search docs

Loading documentation…
    OpenPresentation/opf
    Browse docs
    On this page

    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:

    shell
    npm install -g @openpresentation/cli@0.34.2

    Save a small deck as deck.opf.json. Both slides have an id:

    deck.opf.json
    {
      "$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.

    changes.json
    [
      { "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:

    shell
    opf edit deck.opf.json --patch changes.json

    The command exits 0. With no output file, the edited deck goes to stdout and the report goes to stderr:

    stdout
    {
      "$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"
          ]
        }
      ]
    }
    stderr
    {
      "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:

    shell
    opf edit deck.opf.json --patch changes.json next.opf.json
    opf diff deck.opf.json next.opf.json
    output
    2 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:

    undo.json
    [
      { "op": "remove", "path": "/slides/1/items/2" },
      { "op": "replace", "path": "/slides/0/subtitle", "value": "Draft" }
    ]
    shell
    opf edit next.opf.json --patch undo.json restored.opf.json
    opf diff deck.opf.json restored.opf.json --exit-code
    output
    No 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 unknown op is 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 an add, or of a move or copy target. Array indexes are plain decimals: 01, -1 and 1.0 are errors.
    • test fails 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.

    patch.ts
    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 deck

    Inverse 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 by id, then by content, and finds moves. --format patch prints a patch you can pass to opf edit --patch. It exits 0, or 1 with --exit-code when 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 format writes canonical key order and layout without changing any value. --check exits 1 if a file would change; -i rewrites 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.