com.purplehillsbooks.json

Class JSONDiff

java.lang.Object

com.purplehillsbooks.json.JSONDiff

public class JSONDiff
extends java.lang.Object

The purpose of this class is to produce a "DIFF" comparison of two JSON files. This is useful for JSON files which are holding internationalized string values. Two JSON objects are compared. The keys must be unique; there must not be two members of an object with the same key. The value from one object is compared to the value of the same key from the other.

Nested objects use paths which combine the keys together with dots between them. in the example below, "menu.open" and "menu.close" are path-style keys. These keys again must be unique.

If there is an array, then the elements in the array will be compared in exactly the order they are found, but this might or might not be useful. No attempt is made to find a canonical order for the array elements. The path is constructed using the index in square bracket (e.g. [0], [1], etc.) so that the path is once again unique to specify that value.

The output is a three column CSV file. The first column is the full path key, the second is the value from the first json object, the third column is the corresponding value from the second json object:

JSON File 1:

 {
     "title": "title",
     "pgNumTot": "number of pages",
     "print": "print",
     "menu": {
         "open": "Open",
         "close": "Close"
     }
     "missing": "missing"
 }
 

JSON File 2:

 {
     "title": "titre",
     "pgNumTot": "nombre de pages",
     "print": "imprimer"
     "menu": {
         "open": "Ouvre",
         "close": {"soft":"doux","hard":"fort"}
     },
     "z-extra": "superfluous"
 }
 

The output would then be:

 "menu.close", "Close",   "~object~"
 "menu.open",  "Open",    "Ouvre"
 "missing",    "missing", "~null~"
 "pgNumTot",   "number of pages", "nombre de pages"
 "print",      "print",   "imprimer"
 "title",      "title",   "titre"
 "z-extra",    "~null~",  "superfluous"
 

Note that the keys are in (canonical) ASCII alphabetical order so that the result can always be compared effectively with earlier results. The JSON files need not have keys in alphabetical order, but keeping them that way will make regular text-oriented difference comparisons more useful.

Note that the first file takes precident in defining the structure to compare. That is, all elements in the first file will be considered and iterated as sub-objects even if the second file has those elements missing or different. If the key points to an object in the first file and a non-object in the second file, then the value will be considered to be an object and sub-elements will be followed. However a non-object in the first and an object in the second will be treated like a simple value and show "~object~" as the value. The second object is subservient to this: extra keys in the second object will be ignored in some cases. If the key points to a string value in the first object, but an object value in the second object, then only the string value will be considered.

All or Only Changed

There is a boolean parameter on the constructor to say whether to include all the lines, or just the lines that are different. reportAll=true means that all keys found will be reported, even if the two input files have the same value for that key. reportAll=false will output ONLY the keys that the two files have different values for.

Augmented Output

The first JSON object is considered the superior, and the second parameter is the inferior with potential missing keys. To simlify the adding of keys JSONDiff will extend the second object with values from the first.

a key that maps to an object will create a new object in the second

a key that maps to a string will create a new string in the second. The value will be tagged with "(*)" to identify it as a value that was automatically take from the other. For example, if the first object has:

"key111": "This is a Value"

then JSONDiff will create the following value in the second object:

"key111": "(*)This is a Value"

Command Line Arguments

This class has a main routine so that it can be called as a command-line command where you pass the names of JSON files. The files are read, and the result is written out as a file.

JSONDiff {First-File.json}  {Second-File.json} [-a]

First parameter and second parameter are the two files to read as JSON files and to compare. If either file is not a valid JSON syntax you will get an error. There is a third, optional parameter (-a) which controls the reportAll setting. if this is present, then all keys will be reported whether the values match or not. If this is not present, then only the keys that have differing values are included.

The output will be written to second file name with "diff.csv" on the end. In the example above, the file would be written to Second-File.jsondiff.csv

The augmented object output will be written to second file name with ".augment.json" on the end. In the example above, the file would be written to Second-File.json.augment.json

Constructor Summary

Constructors

Constructor and Description
JSONDiff(boolean reportAll) The boolean parameter on the constructor defines whether to include all the lines, or just the lines that are different.

Method Summary

Modifier and Type	Method and Description
java.util.List<java.util.List<java.lang.String>>	createDiff(JSONObject ob1, JSONObject ob2) Creates a table that represents the difference of the two JSON objects passed in.
static void	main(java.lang.String[] args) The main routine can be called as a command-line command where you pass the names of JSON files.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

JSONDiff

public JSONDiff(boolean reportAll)

The boolean parameter on the constructor defines whether to include all the lines, or just the lines that are different. reportAll=true means that all keys found will be reported, even if the two input files have the same value for that key. reportAll=false will output ONLY the keys that the two files have different values for.

Method Detail

createDiff

public java.util.List<java.util.List<java.lang.String>> createDiff(JSONObject ob1,
                                                                   JSONObject ob2)
                                                            throws java.lang.Exception

Creates a table that represents the difference of the two JSON objects passed in. The table is a list of rows, and each row is a triplet of Strings representing the column values for that row.>

The first column is the full path key, the second is the value from the first json object, the third column is the corresponding value from the second json object

Throws:

java.lang.Exception

main

public static void main(java.lang.String[] args)

The main routine can be called as a command-line command where you pass the names of JSON files. The files are read, and the result is written out as a CSV file.

JSONDiff {First-File.json}  {Second-File.json} [-a]

First parameter and second parameter are the two files to read as JSON files and to compare. If either file is not a valid JSON syntax you will get an error. There is a third, optional parameter (-a) which controls the reportAll setting. if this is present, then all keys will be reported whether the values match or not. If this is not present, then only the keys that have differing values are included.

The output will be written to second file name with "diff.csv" on the end. In the example above, the file would be written to Second-File.jsondiff.csv