Gnieh Diffson

A scala implementation of the RFC-6901 and RFC-6902. It also provides methods to compute diffs between two Json values that produce valid Json patches.

Table of Contents

• Getting Started
• Json Library
• Basic Usage
• Remembering old values
• Patches as Collections of Operations
• Technical Details

Getting Started

This library is published in the Maven Central Repository and is compiled against scala 2.11. You can add it to your sbt project by putting this line to your build description:

libraryDependencies += "org.gnieh" %% "diffson" % "2.0.0"

If you are using maven, add the following dependency to your pom.xml:

<dependency>
  <groupId>org.gnieh</groupId>
  <artifactId>diffson_${scala.version}</artifactId>
  <version>2.0.0</version>
</dependency>

Json Library

Diffson was first developped for spray-json, however, it is possible to use it with any json library of your linking. The only requirement is to have a DiffsonInstance for your json library.

At the moment, diffson provides two instances for spray-json and Play! Json. To use these implementations you need to import the correct instance:

// spray-json
import gnieh.diffson.sprayJson._
// play-json
import gnieh.diffson.playJson._

You also need to add the library in your classpath, as they are marked as provided by diffson to avoid depending on all json libraries when using diffson.

If you want to add support for your favorite Json library, all you need to do is to implement the gnieh.diffson.DiffsonInstance class, which provide the JsonProvider for the specific library. Contribution of new Json libraries in this repository are more than welcome.

Basic Usage

Although the library is quite small and easy to use, here comes a summary of its basic usage.

There are three different entities living in the gnieh.diffson package:

• JsonPointer which allows to parse and manipulate Json pointers as defined in RFC-6901,
• JsonPatch which allows to parse, create and apply Json patches as defined in RFC-6902,
• JsonDiff which allows to compute the diff between two Json values and create Json patches.

Basically if one wants to compute the diff between two Json objects, on can execute the following:

val json1 = """{
              |  "a": 1,
              |  "b": true,
              |  "c": "test"
              |}""".stripMargin

val json2 = """{
              |  "a": 6,
              |  "c": "test2",
              |  "d": false
              |}""".stripMargin

val patch = JsonDiff.diff(json1, json2, false)

println(patch)

which will print the following in the console:

[{
  "op":"replace",
  "path":"/a",
  "value":6
},{
  "op":"remove",
  "path":"/b"
},{
  "op":"replace",
  "path":"/c",
  "value":"test2"
},{
  "op":"add",
  "path":"/d",
  "value":false
}]

You can then apply the patch to json1:

val json3 = patch(json1)
println(json3)

which prints something like:

{
  "d":false,
  "c":"test2",
  "a":6
}

which we can easily verify is the same as json2 modulo reordering of fields.

You may also only want to apply existing patches:

val raw = """[
            |  {
            |    "op": "test",
            |    "path": "/a",
            |    "value": 4
            |  }
            |]""".stripMargin

val patch = JsonPatch.parse(raw)

val json1 = """{ "a": 4 }"""
val json2 = """{ "a": 7 }"""
patch(json1) // ok json1 is returned unchanched
patch(json2) // throws PatchException

Remembering old values

The diff method takes three parameter. The third one indicates whether the generated patch remembers removed and replaced values. When set to true, the Replace and Remove operations take an extra field named old giving the old value. The RFC does not define these fields, but it does not fordbid either to add extra fields. Hence, generated patches can still be interpreted by third party implementations.

Patches as Collections of Operations

Patches may be seen as collections of operations on which you may which to apply some typical collection functions such as map, flatMap, filtering, folding, ...

val patch: JsonPatch = ...

val patch2: JsonPatch =
  for(op @ Add("my" :: "prefix" :: _, _) <- patch)
    yield op

Technical Details

The implementation uses spray-json to manipulate Json objects.

The diff between two arrays is computed by using the Patience Diff algorithm to compute the LCS between both arrays, which is quite simple to implement.

However one can replace the implementation by any other algorithm that implements the gnieh.diffson.Lcs trait, e.g.:

val diff = new JsonDiff(new MyLcsAlgorithm)

then use diff in lieu of JsonDiff in the first usage example.