json-patch

json-patch is a focused Go library for computing and applying structured diffs against JSON documents. It implements two IETF standards: RFC 6902 JSON Patch, an ordered list of add/remove/replace/move/copy/test operations, and RFC 7396 JSON Merge Patch, a shallow object-diff format for describing partial updates. Both are exposed through a small, dependency-light API (DecodePatch, Patch.Apply, CreateMergePatch, MergePatch) that Go services use to accept partial-update requests, reconcile configuration state, or ship diffs instead of full documents over the network.

The library also ships a standalone json-patch CLI for applying one or more patch files to a document piped in over stdin, and it maintains its own internal fork of encoding/json for scanning and decoding rather than depending on the standard library’s package directly, giving it tighter control over number handling and streaming decode behavior. It has been maintained since 2013 and is a common transitive dependency in the Go ecosystem, including in Kubernetes-adjacent tooling that relies on RFC 6902-style PATCH semantics.

What You Get

• DecodePatch / Patch.Apply to parse and apply RFC 6902 JSON Patch operation lists against a JSON document
• CreateMergePatch / MergePatch to compute and apply RFC 7396 JSON Merge Patch diffs between two documents
• MergeMergePatches to combine multiple merge patches into a single equivalent patch
• Equal for structural JSON comparison that ignores whitespace and key ordering
• ApplyOptions for tuning behavior around negative array indices, accumulated copy size limits, missing-path tolerance, and path auto-creation
• A bundled json-patch command-line tool for applying patch files to a document from stdin

Common Use Cases

• Accepting JSON Patch request bodies in HTTP PATCH endpoints (Kubernetes-style partial resource updates)
• Computing a merge patch between two config versions and replaying it elsewhere for reconciliation
• Shipping diffs instead of full documents when syncing state across services or nodes
• Scripting one-off JSON document edits from the command line via the bundled CLI

Under The Hood

Architecture The library is organized as a flat package around two operation types: Patch ([]Operation) for RFC 6902 sequences and a pair of merge functions for RFC 7396. Documents are decoded lazily into lazyNode wrappers backed by a container interface (partialDoc for objects, partialArray for arrays), so get/set/add/remove operations walk and mutate a JSON pointer path without fully materializing the document into Go types up front. patch.go drives RFC 6902 application operation-by-operation; merge.go recursively walks two parsed documents to build or apply an RFC 7396 diff. A small cmd/json-patch binary wraps the library for stdin/file-based use. The core abstraction is the container/lazyNode pair — replacing it would mean rewriting both the patch and merge code paths since both depend on it for path traversal.

Tech Stack Written in Go 1.18+, with a self-contained internal/json package that forks Go’s standard encoding/json scanner, decoder, and encoder rather than importing it directly, giving the library control over raw-message handling during patch traversal. The only external runtime dependency is github.com/jessevdk/go-flags, used solely by the CLI subcommand for flag parsing; the core library has effectively zero third-party dependencies. Distributed as a Go module at the /v5 subpath, with an older v4 line still published separately via gopkg.in.

Code Quality Tests use Go’s standard testing package with table-style and round-trip style cases across patch_test.go and merge_test.go — no assertion library is used, comparisons are done via direct reflect.DeepEqual and custom JSON-structural-equality helpers. There’s also a fuzz test harness in internal/json, and the project runs continuous fuzzing through OSS-Fuzz via a dedicated GitHub Actions workflow (cifuzz.yml) in addition to a standard go test CI job — a meaningfully more rigorous quality bar than typical for a small utility library, given how easy JSON patch edge cases are to get wrong. Errors are returned as typed sentinel values (ErrTestFailed, ErrMissing, ErrInvalidIndex, etc.) and dedicated error structs (AccumulatedCopySizeError, ArraySizeError) rather than opaque strings.

What Makes It Unique Most JSON-diffing libraries pick one of RFC 6902 or RFC 7396; this one implements both under a single API and adds MergeMergePatches to compose multiple merge patches into one equivalent patch — a capability not part of either RFC and useful for batching config updates. Combining that with continuous fuzz testing against a hand-rolled JSON scanner gives it unusually strong correctness guarantees for a narrow-scope utility library.