json-patch

json-patch is a Rust crate implementing the RFC 6902 JSON Patch and RFC 7396 JSON Merge Patch specifications on top of serde_json::Value. It lets applications apply a sequence of add/remove/replace/move/copy/test operations to a JSON document, or merge a partial JSON document into an existing one, without hand-rolling patch logic.

Beyond applying patches, the crate can diff two JSON documents to produce a minimal patch describing the difference, and optionally integrates with schemars and utoipa for JSON Schema and OpenAPI documentation of the Patch type. It is widely used as a building block in configuration systems, REST APIs supporting partial updates, and tools that need to compute or replay structured JSON diffs.

What You Get

• A Patch type that deserializes a JSON Patch document and a patch() function to apply it to a serde_json::Value
• A merge() function implementing RFC 7396 JSON Merge Patch semantics
• A diff() function (behind the default diff feature) that computes a minimal JSON Patch between two documents
• Optional schemars and utoipa feature flags for JSON Schema / OpenAPI integration of patch types
• Well-defined error types (via thiserror) distinguishing test-operation failures from structural errors

Common Use Cases

• Implementing HTTP PATCH endpoints that accept an RFC 6902 patch body and apply it to a stored JSON document
• Computing a diff between two versions of a JSON configuration to send only the changed fields over the wire
• Merge-patching partial JSON payloads into existing records, following RFC 7396 semantics
• Building undo/redo or audit-log systems that record and replay JSON patch operations

Under The Hood

Architecture - The crate is organized around two small modules: lib.rs, which defines the Patch/PatchOperation enum, the patch() and merge() entry points, and error types; and diff.rs, which implements the diffing algorithm behind the default diff feature. Patch application walks the target serde_json::Value tree using pointer paths resolved via the jsonptr crate, mutating the document in place for add/remove/replace/move/copy/test operations, and returning a typed PatchError on pointer-resolution or test-mismatch failures.

Tech Stack - Built on serde/serde_json for JSON representation and derive-based (de)serialization of patch operations, jsonptr for RFC 6901 JSON Pointer resolution, and thiserror for ergonomic error types. Optional dependencies schemars and utoipa are gated behind feature flags to add JSON Schema and OpenAPI documentation support without imposing them on consumers who don’t need it. The crate targets the 2021 Rust edition and has no unsafe code.

Code Quality - The crate has strong test coverage: a tests/ directory with basic.rs and a suite.rs that runs the shared JSON Patch/Merge Patch conformance test suites from the specs/ directory (tests.json, merge_tests.json, spec_tests.json, revert_tests.json), plus dedicated schemars.rs and utoipa.rs tests for the optional integrations. #![warn(missing_docs)] is set at the crate root, and public items carry doc comments with runnable examples. CI runs via GitHub Actions with Codecov coverage tracking.

API Design - The public API is intentionally minimal: Patch, patch(), and merge() cover the two RFCs with no extraneous surface area, and both entry points work directly with serde_json::Value, so there’s no bespoke document model to learn. Getting started requires only adding the crate and calling patch()/merge() with a value already in hand, and doc comments on the crate root show both flows end-to-end.