Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,14 @@
Tests cover the RFC's Appendix B number vectors, its sample document and its
key-sorting example. The writer does not hash or sign. The existing writer and
its scalar key order are unchanged.
- Add `JSONPatch.difference(from:to:options:)` and `differenceWithReport`, which
compute RFC 6902 operations that turn one exact value into another. Equal values
(exact decimals, scalar keys, order-independent objects) produce no operation;
objects diff by key, arrays keep their equal prefix and suffix and compare the
rest by position, other changes are replaced. The result is deterministic and
applies to the source to give the target, but is not minimal and never uses
`move`, `copy` or `test`. One cumulative patch ledger covers both inputs and
the produced operations.

## Unreleased — 1.9.1 hygiene

Expand Down
20 changes: 20 additions & 0 deletions Documentation/Architecture/Patch.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,26 @@ Reject negative index construction, invalid escape syntax and configured token/b

Pointer construction is a convenience over strict tokens. It adds no wildcards, JSONPath, jq expressions, automatic parent creation or ambiguous autovivification. Test empty keys, slash/tilde, Unicode scalar identity, numeric object keys, percent fragments and repeated resolution with one immutable Pointer.

## Structural difference

`JSONPatch.difference(from:to:options:)` (1.10) produces RFC 6902 operations that
turn a source value into a target value, under one cumulative `.patch` ledger
that admits both inputs, charges every comparison, Pointer and operation, and
checks cancellation in its loop. The result is deterministic and always applies
to the source to give a value equal to the target; it is not a minimal edit script.

- Equality is the exact model's: equal decimals (`1.0` and `1`), decoded scalar
keys and order-independent objects produce no operation. Canonically
equivalent but scalar-distinct keys are different members.
- Objects: members only in the source are removed (source order), members only in
the target are added (target order), and shared members are compared recursively.
- Arrays: the longest equal prefix and suffix are kept; the remaining elements
are compared by position, surplus source elements are removed from the highest
index down, and surplus target elements are added in order.
- Different kinds and unequal scalars are replaced; a root change uses the empty Pointer.
- No `move`, `copy` or `test` operation is generated. An insertion at the front of
a long array therefore produces one operation per shifted element.

## JSON Merge Patch

JSONMergePatch implements RFC 7396 in the JSONPatch product. This offers an object-shaped partial-update use case beside RFC 6902 operations. The new type uses the exact JSON model and an explicitly bounded staged application.
Expand Down
6 changes: 3 additions & 3 deletions Documentation/Qualification/TestDiscovery.json
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
"JSONSchemaTests": 79,
"JSONRegexRuntimeTests": 16,
"JSONStreamingTests": 36,
"JSONPatchTests": 16,
"JSONPatchTests": 22,
"JSONIntegrationTests": 45,
"JSONHTMLTests": 97,
"JSONBridgesTests": 10,
Expand Down Expand Up @@ -77,7 +77,7 @@
"JSONSchemaTests": 79,
"JSONRegexRuntimeTests": 16,
"JSONStreamingTests": 36,
"JSONPatchTests": 16,
"JSONPatchTests": 22,
"JSONIntegrationTests": 45,
"JSONHTMLTests": 81,
"JSONBridgesTests": 10,
Expand All @@ -93,7 +93,7 @@
"JSONSchemaTests": 79,
"JSONRegexRuntimeTests": 16,
"JSONStreamingTests": 36,
"JSONPatchTests": 16,
"JSONPatchTests": 22,
"JSONIntegrationTests": 45,
"JSONHTMLTests": 81,
"JSONBridgesTests": 10,
Expand Down
2 changes: 1 addition & 1 deletion Sources/JSONCLIEngine/CLIBuildIdentity.swift
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,6 @@
// Generated by Scripts/generate_cli_identity.py; excludes this file.
// SHA-256 of the ordered Package.swift + Sources content manifest (DocC catalogs excluded), not a Git commit.
package enum CLIBuildIdentity {
package static let revision = "sha256:528b7f15a54f6c25125196ffef9ec2979a2b05c549f214ac8c643503e0becc48"
package static let revision = "sha256:ab828e1c70d46c10f7a6431f5e9ef22ac469b8609778e3e99b7a0f6af77891ff"
package static let kind = "source-sha256"
}
10 changes: 10 additions & 0 deletions Sources/JSONPatch/Documentation.docc/JSONPatch.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,14 @@ no partially changed document and leaves the caller value unchanged.
``JSONPatchResult`` distinguishes a removed root from a document containing
JSON null. A subsequent root add can recreate a removed document.

``JSONPatch/difference(from:to:options:)`` computes a patch that turns one value
into another. It is structural and deterministic, not minimal: equal values
(by exact decimal, scalar and order-independent object equality) produce no
operation, object members are removed, added or compared by exact key, arrays
keep their equal prefix and suffix and compare the rest by position, and other
changes are replaced. It never emits `move`, `copy` or `test`, and applying the
result to the source always yields a value equal to the target.

``JSONMergePatch`` implements RFC 7396: null object members remove properties,
object patches recurse with explicit frames, and other values replace the
selected value. A root null replaces the document with JSON null. Arrays are
Expand All @@ -33,6 +41,8 @@ earlier oversized stage. Reports expose logical accounting, not process RSS.
### JSON Patch

- ``JSONPatch``
- ``JSONPatch/difference(from:to:options:)``
- ``JSONPatch/differenceWithReport(from:to:options:)``
- ``JSONPatchOperation``
- ``JSONPatchResult``
- ``JSONPatchOptions``
Expand Down
143 changes: 143 additions & 0 deletions Sources/JSONPatch/JSONPatchDifference.swift
Original file line number Diff line number Diff line change
@@ -0,0 +1,143 @@
// SPDX-License-Identifier: Apache-2.0
// Original implementation of a bounded structural difference producing RFC 6902 operations.
import JSON

extension JSONPatch {
package init(admitted operations: [JSONPatchOperation]) { self.operations = operations }

/// Computes a patch that turns `source` into `target` when applied to `source`.
///
/// The difference is structural and deterministic, not a minimal edit script:
///
/// - Equal values, using the exact model's equality (decimal value, decoded
/// scalars, order-independent objects), produce no operation. `1.0` and `1`
/// are equal, so neither is replaced by the other.
/// - Object members are compared by exact key. Members only in `source` are
/// removed, members only in `target` are added in `target` order, and shared
/// members are compared recursively. A changed member order alone produces no
/// operation, because object equality ignores order.
/// - Arrays keep their longest equal prefix and suffix. The remaining elements
/// are compared pairwise by position; surplus `source` elements are removed
/// from the highest index down, and surplus `target` elements are added in order.
/// Elements are never moved or copied, so an inserted element at the front
/// of a long array can produce many operations.
/// - Values of different kinds, and unequal scalars, are replaced. A root
/// change replaces the root through the empty Pointer.
///
/// The result contains no `test`, `move` or `copy` operations.
///
/// - Returns: A patch whose application to `source` yields a value equal to `target`.
/// - Throws: Resource failure for oversized inputs, operation counts or Pointer
/// lengths, or cancellation.
///
/// - Parameters:
/// - source: The value the patch will be applied to.
/// - target: The value the patch must produce.
/// - options: Finite limits for admission, comparison and the produced operations.
public static func difference(from source: JSON, to target: JSON, options: JSONPatchOptions = .init()) throws -> JSONPatch {
try differenceWithReport(from: source, to: target, options: options).result
}
/// Computes the structural difference with cumulative work accounting.
///
/// See ``difference(from:to:options:)`` for the semantics.
///
/// - Returns: The patch and the charged counts of the single invocation ledger.
/// - Throws: Resource failure for oversized inputs, operation counts or Pointer
/// lengths, or cancellation.
///
/// - Parameters:
/// - source: The value the patch will be applied to.
/// - target: The value the patch must produce.
/// - options: Finite limits for admission, comparison and the produced operations.
public static func differenceWithReport(from source: JSON, to target: JSON, options: JSONPatchOptions = .init()) throws -> JSONOperationReport<JSONPatch> {
var meter = try JSONWorkMeter(limits: options.limits, domain: .patch)
let patch = try difference(from: source, to: target, meter: &meter)
return .init(result: patch, statistics: meter.statistics())
}
package static func difference(from source: JSON, to target: JSON, meter: inout JSONWorkMeter) throws -> JSONPatch {
try JSONAdmission.value(source, meter: &meter)
try meter.resetValueBounds(); try JSONAdmission.value(target, meter: &meter)
enum Step {
/// Compare two values found at the same path.
case compare(path: [JSONKey], source: JSON, target: JSON)
/// Emit an operation after the steps pushed before it have run.
case emit(JSONPatchOperation)
}
var operations: [JSONPatchOperation] = []
var stack: [Step] = []
func push(_ step: Step, meter: inout JSONWorkMeter) throws {
try meter.work(); try meter.retain(JSONLogicalWeights.frame); stack.append(step)
}
func pointer(_ path: [JSONKey], meter: inout JSONWorkMeter) throws -> JSONPointer {
try JSONPointer.decodedTokens(path, meter: &meter)
}
func extended(_ path: [JSONKey], _ key: JSONKey, meter: inout JSONWorkMeter) throws -> [JSONKey] {
try meter.require(.pointerTokens, UInt64(path.count) + 1)
for _ in path { try meter.work() }
try meter.retain(16); return path + [key]
}
func index(_ value: Int, meter: inout JSONWorkMeter) throws -> JSONKey {
try JSONKey(String(value), meter: &meter)
}
try push(.compare(path: [], source: source, target: target), meter: &meter)
while let step = stack.popLast() {
try meter.release(JSONLogicalWeights.frame); try meter.work()
switch step {
case .emit(let operation):
try meter.require(.operations, UInt64(operations.count) + 1)
try meter.retain(JSONLogicalWeights.frame); operations.append(operation)
case .compare(let path, .object(let a), .object(let b)):
// Steps are pushed in reverse so they run in source/target order.
var pending: [Step] = []
for member in a {
try meter.work()
if try b.lookup(member.key.string, meter: &meter) == nil {
pending.append(.emit(.remove(path: try pointer(extended(path, member.key, meter: &meter), meter: &meter))))
}
}
for member in b {
try meter.work()
let childPath = try extended(path, member.key, meter: &meter)
if let existing = try a.lookup(member.key.string, meter: &meter) {
pending.append(.compare(path: childPath, source: existing, target: member.value))
} else {
pending.append(.emit(.add(path: try pointer(childPath, meter: &meter), value: member.value)))
}
}
for item in pending.reversed() { try push(item, meter: &meter) }
case .compare(let path, .array(let a), .array(let b)):
let shared = min(a.count, b.count)
var prefix = 0
while prefix < shared, try JSONComparison.equals(a[prefix], b[prefix], meter: &meter) { prefix += 1 }
var suffix = 0
while suffix < shared - prefix,
try JSONComparison.equals(a[a.count - 1 - suffix], b[b.count - 1 - suffix], meter: &meter) { suffix += 1 }
let middleA = a.count - prefix - suffix, middleB = b.count - prefix - suffix
let paired = min(middleA, middleB)
var pending: [Step] = []
for offset in 0..<paired {
try meter.work()
let position = prefix + offset
pending.append(.compare(path: try extended(path, index(position, meter: &meter), meter: &meter),
source: a[position], target: b[position]))
}
// Highest index first, so each removal leaves lower indices in place.
for position in stride(from: prefix + middleA - 1, through: prefix + paired, by: -1) {
try meter.work()
pending.append(.emit(.remove(path: try pointer(extended(path, index(position, meter: &meter), meter: &meter), meter: &meter))))
}
for position in (prefix + paired)..<(prefix + middleB) {
try meter.work()
pending.append(.emit(.add(path: try pointer(extended(path, index(position, meter: &meter), meter: &meter), meter: &meter),
value: b[position])))
}
for item in pending.reversed() { try push(item, meter: &meter) }
case .compare(let path, let a, let b):
if try !JSONComparison.equals(a, b, meter: &meter) {
try push(.emit(.replace(path: try pointer(path, meter: &meter), value: b)), meter: &meter)
}
}
}
return JSONPatch(admitted: operations)
}
}
Loading
Loading