json-format

In this post, we’ll go over how to use json-format, an easy to use CLI tool to format json.

Why use json-format?

If you work with json and use git, you’ll want json-format. json-format formats json to make the git-diffs as clear as possible.

If a json file’s json value hasn’t changed, then its git diff will be empty. No more dealing with a change in white space. No more dealing with a different key ordering.

If a json file’s json value has changed, then there will only be one difference per line. Since git diffs are line based, each entry change in an array or object corresponds to a single line change. This makes diffs a pleasure to read. One change stays on one line. No line changes because one of three values changed.

What is formatted json?

Formatted json sounds good. Who wants ugly json? But…what is formatted json? For this post, we’ll say it’s the output of jq -S (ignoring color) for an inputted json value.

The output that satisfies two important properties:

  1. If two formatted json values are equivalent as json if and only if they’re equivalent as text. For example [] and [ ] are equivalent as json, both are the empty list. But they are not equivalent as text.

  2. There is exactly one array element or object element per line. For example: [1, 2] is not formatted because there are two array elements per line.

As a spec, json provides flexibility with whitespace, newlines, and object key order. As such, formatting json means throwing away this flexibility. The benefits are completely worth it however.

Why not use jq -S?

jq -S is great, but using jq to changing files in place is a pain. json-format takes care of that pain by wrapping around jq -S.

To be fair, json-format is a bit specialized. I could’ve built either a general wrapper ipjq for “in-place jq” or even an ipedit which takes in a file and a list of command args and to perform an in-place edit with programs that don’t provide an inplace edit flag.

But, in practice I use json-format a lot (I aliased it to jf) and rarely do in-place edits with other programs. If someone would like to submit a pull request to implement ipjq or ipedit and change json-format to be a special case of it, I’d be happy to review it.

Using json-format

Installing

json-format is part of the json-toolkit. Installing it only takes a few steps which are outlined in the README.

Examples

With a file

$ echo '[1, 2, 3]' > ugly.json
$ json-format ugly.json
$ cat ugly.json
[
  1,
  2,
  3
]

With stdin

$ echo '[1, 2, 3]' | json-format 
[
  1,
  2,
  3
]

Aliasing json-format

I use json-format so much, I’ve aliased it to jf. Just add

$ echo 'alias jf="json-format"' >> ~/.bash_aliases
$ source ~/.bash_aliases
$ echo '[1, 2, 3]' | jf
[
  1,
  2,
  3
]

Conclusion

In this post, we’ve seen that formatted json is a must have for git users. We’ve seen how to install it as part of the json-toolkit and how to use it to format both stdin and files in place. We’ve seen how to alias it to make it even faster to use.

Next week we’ll go over how to use the json-toolkit’s data converters to convert anything into json, json into anything, and anything into anything. If you don’t want to miss out, just click the “Subscribe now” button below.