jsonpatch

JSON Patch Go

A Go-native JSON Patch+ library with compiled patches, type-preserving results, and immutable-by-default application

Features

• Compiled patch path: Validate, capability-check, and freeze operations once, then reuse an isolated Patch.
• Type-preserving results: Apply converts patched documents back to the caller's original Go type when safe.
• Immutable by default: Apply clones before execution; ApplyInPlace makes mutation explicit.
• Capability-gated vocabulary: RFC 6902 is the default; predicates, regex predicates, and extended operations opt in at compile time.
• Explicit document shapes: Plain string is scalar text; use JSONText or []byte for JSON text.
• Structured errors: Match stable failure classes with errors.Is and inspect operation context with errors.As.
• Wire-format codecs: Use JSON, compact array, or MessagePack codecs without moving execution semantics out of operations.

Installation

go get github.com/kaptinlin/jsonpatch

Requires Go 1.26.5+.

Quick Start

Use this path when you have Go-built operations and want an immutable result while preserving the original document.

package main

import (
    "fmt"
    "log"

    "github.com/kaptinlin/jsonpatch"
    "github.com/kaptinlin/jsonpatch/op"
)

func main() {
    doc := map[string]any{"name": "John", "tags": []any{"go"}}

    patch, err := jsonpatch.Compile(
        op.NewTest([]string{"name"}, "John"),
        op.NewReplace([]string{"name"}, "Jane"),
        op.NewAdd([]string{"email"}, "jane@example.com"),
    )
    if err != nil {
        log.Fatal(err)
    }

    result, err := jsonpatch.Apply(patch, doc)
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(result.Doc["name"]) // Jane
    fmt.Println(doc["name"])        // John
}

Core API

Capabilities

Default compilation accepts only RFC 6902 operations. Enable additional operation families explicitly.

patch, err := jsonpatch.CompileJSON(data,
    jsonpatch.WithCapabilities(
        jsonpatch.RFC6902,
        jsonpatch.Predicate,
        jsonpatch.RegexPredicate,
        jsonpatch.Extended,
    ),
)
if err != nil {
    return err
}

Use jsonpatch.AllCapabilities when your boundary intentionally accepts every operation implemented by the package.

Document Shapes

patch, err := jsonpatch.CompileJSON([]byte(`[{"op":"replace","path":"/name","value":"Jane"}]`))
if err != nil {
    return err
}

result, err := jsonpatch.Apply(patch, jsonpatch.JSONText(`{"name":"John"}`))
if err != nil {
    return err
}

fmt.Println(result.Doc)

In-Place Application

Use ApplyInPlace when mutation is intentional and visible at the call site.

doc := map[string]any{"name": "John"}
patch, err := jsonpatch.Compile(op.NewReplace([]string{"name"}, "Jane"))
if err != nil {
    return err
}

if err := jsonpatch.ApplyInPlace(patch, &doc); err != nil {
    return err
}

fmt.Println(doc["name"])

Structured Errors

Compile and apply failures wrap stable sentinel errors and expose operation context. A failed apply returns a nil result; inspect *jsonpatch.Error for the failing operation index and fields.

result, err := jsonpatch.Apply(patch, doc)
if err != nil {
    if errors.Is(err, jsonpatch.ErrTestFailed) {
        return err
    }

    var patchErr *jsonpatch.Error
    if errors.As(err, &patchErr) {
        fmt.Printf("operation %d %s %s failed: %v\n",
            patchErr.Index(),
            patchErr.Op(),
            patchErr.Path(),
            patchErr.Cause(),
        )
    }
    return err
}

_ = result.Doc

Codecs

Codec packages translate wire formats. Operation behavior stays in op/.

JSON Codec

Use codec/json when you want to encode or decode JSON-shaped operation values directly.

operations := []jsoncodec.Operation{
    {Op: "replace", Path: "/name", Value: "Jane"},
}

patch, err := jsonpatch.CompileOperations(operations)
if err != nil {
    return err
}

Compact Codec

Use codec/compact for compact array-form operations with segment-array paths.

ops := []jsonpatch.Op{
    op.NewAdd([]string{"name"}, "Jane"),
    op.NewInc([]string{"version"}, 1),
}

encoded, err := compact.EncodeJSON(ops)
if err != nil {
    return err
}

decoded, err := compact.DecodeJSON(encoded)
if err != nil {
    return err
}

fmt.Println(len(decoded))

Binary Codec

Use codec/binary for MessagePack encoding. Decode accepts exactly one complete patch value and rejects malformed operation frame lengths, trailing bytes, and concatenated values.

codec := binary.New()
ops := []jsonpatch.Op{
    op.NewAdd([]string{"name"}, "Jane"),
    op.NewInc([]string{"version"}, 1),
}

data, err := codec.Encode(ops)
if err != nil {
    return err
}

decoded, err := codec.Decode(data)
if err != nil {
    return err
}

fmt.Println(len(decoded))

Examples

Explore runnable examples in examples/:

• examples/basic-operations/
• examples/array-operations/
• examples/conditional-operations/
• examples/copy-move-operations/
• examples/string-operations/
• examples/struct-patch/
• examples/map-patch/
• examples/json-bytes-patch/
• examples/json-string-patch/
• examples/apply-in-place/
• examples/compact-codec/
• examples/binary-codec/
• examples/error-handling/
• examples/batch-update/

Development

task test           # Run all tests with race detection
task golangci-lint  # Run golangci-lint
task lint           # Run golangci-lint and tidy checks
task vet            # Run go vet
task bench          # Run benchmarks
task verify         # Run the complete release gate

For development guidelines, see AGENTS.md. For recorded behavior contracts, see SPECS/.

Contributing

See CONTRIBUTING.md.

License

This project is licensed under the MIT License - see the LICENSE file for details.