JSON-Patch

Schema-driven JSON patching with semantic paths, conflict detection, and multi-user collaboration support.

English | 中文

✨ Why Schema-JSON-Patch?

Traditional JSON Patch (RFC 6902) uses array indices like /items/0/name. When array order changes, patches break.

Schema-JSON-Patch solves this with semantic paths:

- Traditional: /items/0/name     ← Breaks when array order changes
+ Semantic:    /items/id1/name   ← Always targets the right object

Key Differentiators

Feature	Traditional JSON Patch	Schema-JSON-Patch
Array element targeting	Index-based (fragile)	Primary key-based (stable)
Multi-user collaboration	❌	✅ Conflict detection & resolution
Patch validation	❌	✅ Schema-aware validation

⚡ Performance

Benchmark results for core operations with 100 items:

Feature	Scenario	Performance (ops/sec)
generatePatches	100 Items, 20% Change	~1,500
generatePatchesFromData	500 Items, 10% Change	~1,500 ⚡
applyPatches	100 Items, Sparse	~3,000
detectConflicts	2 Groups, Mixed	~10,900
resolveConflicts	10 Conflicts	~270,000

Note

For the full benchmark report, please see BENCHMARKS.

📝 Demo

Try the interactive demo: https://waveoxhub.github.io/schema-json-patch/

📦 Installation

# npm
npm install @waveox/schema-json-patch

# yarn
yarn add @waveox/schema-json-patch

# pnpm
pnpm add @waveox/schema-json-patch

🚀 Quick Start

import { generatePatches, applyPatches, Schema } from '@waveox/schema-json-patch';

// Define your data structure
const schema: Schema = {
    $type: 'object',
    $fields: {
        users: {
            $type: 'array',
            $item: {
                $type: 'object',
                $pk: 'id', // Primary key for semantic paths
                $fields: {
                    id: { $type: 'string' },
                    name: { $type: 'string' },
                },
            },
        },
    },
};

const original = { users: [{ id: 'u1', name: 'Alice' }] };
const modified = { users: [{ id: 'u1', name: 'Alice Updated' }] };

// Generate semantic patches
const patches = generatePatches(schema, JSON.stringify(original), JSON.stringify(modified));
// → [{ op: "replace", path: "users/u1/name", value: "Alice Updated", hash: "..." }]

// Apply patches
const result = applyPatches(JSON.stringify(original), patches, schema);

For detailed API documentation, see @waveox/schema-json-patch.

🤝 Contributing

git clone https://github.com/waveoxhub/schema-json-patch
cd schema-json-patch
pnpm install
pnpm build
pnpm test

📄 License

MIT