jset

jset is a command-line tool for performing set operations on a list of json files

Installation

TODO

Whirlwind Tour

jset requires at least two json files to work with, but can work with any number of json files. The basic structure of a jset command is as follows (where FILE is a path to a JSON file):

jset <operation> [flags] FILE FILE [...FILE]

By default all output is pretty printed, but this can be disabled using the -c flag. This will be done in all examples below to make them more readable.

Union

jset union computes the set union between two or more json files.

Objects

Fields are recursively merged together.

$ jset union -c <(echo '{"a":{"b": "c"}}') <(echo '{"a":{"c": "d"},"e":"f"}')
{"a":{"b":"c","c":"d"},"e":"f"}

When conflicting keys exist, later files take precedence over earlier files.

$ jset union -c <(echo '{"a":"b"}') <(echo '{"a":"c"}')
{"a":"c"}

Arrays

Elements from each array are concatenated together.

$ jset union -c <(echo '["a","b","c"]') <(echo '["d","e","f"]')
["a","b","c","d","e","f"]

Duplicate elements from later lists are ignored in final result.

$ jset union -c <(echo '["a","b","c"]') <(echo '["b","c","d"]')
["a","b","c","d"]

Primitives (numbers, bools, strings, null)

Primitive values union successfully if the values are identical, otherwise no union is found and the program execution fails.

$ jset union -c <(echo '"a"') <(echo '"a"')
"a"

$ jset union -c <(echo '"a"') <(echo '"b"')
$ echo $?
1

Intersect

jset intersect computes the set intersection between two or more json files.

Objects

New object is returned with fields that exist in all files, recursively.

$ jset intersect -c <(echo '{"a":{"b":"c","g":"i"}}') <(echo '{"a":{"b":"c","g":"h"},"e":"f"}')
{"a":{"b":"c"}}

Arrays

Elements from first file are retained as long as they exist in all subsequent files.

$ jset intersect -c <(echo '["a","b","c"]') <(echo '["a","d","e"]')
["a"]

Primitives (numbers, bools, strings, null)

Primitive values intersect successfully if the values are identical, otherwise no intersection is found and the program execution fails.

$ jset intersect -c <(echo '"a"') <(echo '"a"')
"a"

$ jset intersect -c <(echo '"a"') <(echo '"b"')
$ echo $?
1

Difference

jset difference (alias: jset diff) computes the set difference between two or more json files. This is done iteratively with the 2nd file being subtracted from the first, the 3rd being subtracted from the difference between the 1st and 2nd and so on.

An example with four files would be processed in the following way:

((1-2)-3)-4

# or more simply
1-2-3-4

Objects

The returned object is the first file with the second file subtracted from it, recursively. Uknown fields in the subsequent files are ignored.

$ jset diff -c <(echo '{"a":{"b":"c","g":"i"}}') <(echo '{"a":{"b":"c","g":"h"},"e":"f"}')
{"a":{"g":"i"}}

Arrays

Elements from first file are removed if they appear in any subsequent files.

$ jset diff -c <(echo '["a","b","c"]') <(echo '["a","d","e"]')
["b","c"]

Primitives (numbers, bools, strings, null)

Performing set differences on primitive values will return the first value when all other values are not equal, otherwise it will fail.

Note: I didn't have any use-case for doing set differences on primitives so I don't know if this is really useful behavior. 🤷

$ jset diff -c <(echo '"a"') <(echo '"a"')
$ echo $?
1

$ jset diff -c <(echo '"a"') <(echo '"b"')
"a"