jsondiffprinter

The Go package github.com/breml/jsondiffprinter provides the means to pretty print semantic differences between JSON data based on JSON Patch (RFC 6902).

The package it self does not provide the necessary logic to calculate the differences between JSON documents. For this, it relys on external package and uses the JSON Patch format as interface.

Motivation

This package has been initially built for usage in tfreveal, a tool to pretty print differences in Terraform plans. Given its roots in printing differences in the way Terraform is doing it, this package contains some specialized features targeting this use case. This being said, the package is nevertheless also very useful to print differences between any JSON documents.

Usage as Library

Installation

go get github.com/breml/jsondiffprinter

Usage

Example using the package (source examples/basic/main.go):

package main

import (
	_ "embed"
	"fmt"
	"os"

	"github.com/breml/jsondiffprinter"
)

//go:embed source.json
var source []byte

//go:embed patch.json
var patch []byte

func main() {
	formatter := jsondiffprinter.NewJSONFormatter(os.Stdout)
	err := formatter.Format(source, patch)
	if err != nil {
		fmt.Fprintln(os.Stderr, err)
		os.Exit(1)
	}
}

To generate the JSON patch an additional package is required. examples/diff/main.go contains a simple example. Packages, that can be used to calculate the diff between two JSON documents as JSON Patch can be found further down. Inspiration on how to integreate with them can be taken from cmd/jd/main.go.

Usage as command

Install jd

Download the latest release from the releases page.

Use jd

jd before.json after.json

Example output:

  {
    "baz": "qux",
-   "foo": "bar",
    "noz": true
  }

For the full list of supported options, run jd --help.

Supported JSON Patch Libraries

jd includes the following libraries to calculate the JSON patch:

• cameront: https://github.com/cameront/go-jsonpatch
• herkyl: https://github.com/herkyl/patchwerk
• mattbaird: https://github.com/mattbaird/jsonpatch
• MianXiang: https://github.com/520MianXiangDuiXiang520/json-diff
• snorwin: https://github.com/snorwin/jsonpatch
• VictorLowther: https://github.com/VictorLowther/jsonpatch2
• wI2L: https://github.com/wI2L/jsondiff

Development

In order to reduce the number of 3rd party dependencies, the package github.com/breml/jsondiffprinter does not contain the logic to calculate the differences between two JSON documents. Instead, it relies on external packages that provide this functionality. Since the command jd and the examples do require this functionality, they live in their own modules, that is, they have their own go.mod file.

To simplify the work with the different modules, the go.work file is used, which is also contained in the repository.

Test Data

The test cases for jsondiffprinter are in the testdata directory. They use the txtar format to store the test data. The test cases are generated by the cmd/generate_testdata/main.go script. The task to update the test data is provided in the Taskfile.yml and can be executed by running task generate. This requires the task tool to be installed. Please refer to the official documentation.

Author

Copyright 2024 by Lucas Bremgartner (breml)

License

MIT License