JSON(1) json tool manual JSON(1)

NAME

json - (aka "jsontool") JSON love for your command line.

SYNOPSIS

something-generating-JSON-on-stdout | json [OPTIONS] [LOOKUPS]

json -f FILE [OPTIONS] [LOOKUPS...]

DESCRIPTION

Pipe in your JSON for pretty-printing, JSON validation, filtering, and
modification. Supply one or more LOOKUPS to extract a subset of the JSON.
HTTP header blocks are skipped by default.

Grouping

(Added in json v4.) Use '-g' or '--group' to group objects (into an array
of objects) or concatenate arrays (into a single array) separated by no
space or by a newline. This can be helpful for, e.g.:


$ cat *.json | json -g ...


and similar.

In json v3 and earlier, this used to be called "auto-arrayification" and
was implicit. See the COMPATIBILITY section below.

Merging

(Added in json v4.) Use '--merge' or '--deep-merge' to merge adjacent
JSON objects in the input. Keys in the last object win.


$ echo '{"one":"un","two":"deux"}
{"one":"uno","three":"tres"}' | json --merge
{
"one": "uno",
"two": "deux",
"three": "tres"
}


This could be useful for merging multiple config files, e.g.:


$ cat /opt/app/etc/defaults.json \
/etc/app/config.json \
~/.app/config.json | json --merge
...

Execution

Use the -e CODE option to execute code on the input JSON.


$ echo '{"name":"trent","age":38}' | json -e 'age++'
{
"name": "trent",
"age": 39
}


If input is an array, this will automatically process each item
separately.

Conditional filtering

Use the -c CODE option to filter the input JSON.


$ echo '[{"age":38},{"age":4}]' | json -c 'age>21'
[{"age":38}]


If input is an array, this will automatically process each item
separately.

Lookups

Use lookup arguments to extract particular values:


$ echo '{"name":"trent","age":38}' | json name
trent


Use -a for array processing of lookups and tabular output:


$ echo '{"name":"trent","age":38}' | json name
trent
$ echo '[{"name":"trent","age":38},
{"name":"ewan","age":4}]' | json -a name age
trent 38
ewan 4


Integral values work for array index lookups:


$ echo '["a", "b", "c"]' | json 1
b


Negative array indeces are also supported:


$ echo '["a", "b", "c"]' | json -1
c
$ echo '["a", "b", "c"]' | json -2
b


Pretty-printing
Output is "jsony" by default: 2-space indented JSON with one exception, a
single string value is printed without quotes.


$ echo '{"name": "trent", "age": 38}' | json
{
"name": "trent",
"age": 38
}


Use -o json for explicit JSON, -o json-N for N-space indent:


$ echo '{"name": "trent", "age": 38}' | json -o json-0
{"name":"trent","age":38}


Use -H to exclude a leading HTTP header block as from curl -i.

Listing keys

Sometimes you want the list of keys for an object. Use -k or --keys for
that:


$ echo '{"name": "trent", "age": 38}' | json -k
[
"name",
"age"
]
$ echo '{"name": "trent", "age": 38}' | json -ka
name
age

OPTIONS

-h, --help
Print this help info and exit.

--version
Print version of this command and exit.

-q, --quiet
Don't warn if input isn't valid JSON.

By default json will process input from stdin. Alternative, an input file
(or files) can be specified:

-f FILE
Specify an input file (instead of stdin).

If your JSON output is a REST API response, it might include the headers
(e.g. when calling with curl -i). By default json will pass those headers
through (without choking on them). However if you want them stripped you
can use:

-H drop any HTTP header block (as from curl -i ...)

Other pre-JSON input handling:

-g, --group
Group adjacent objects into an array of objects, or concatenate
adjacent arrays into a single array.

--merge, --deep-merge
Merge adjacent objects into a single object with merged keys.
Values in later objects win. Use --deep-merge to recursively merge
keys in objects.

You can process elements of an input array separately and generate
tabular output:

-a, --array
Process input as an array of separate inputs and output in tabular
form.

-d DELIM
Delimiter character for tabular output (default is ' ').

-A Process input as a single object, i.e. stop -e and -c
automatically processing each item of an input array.

You can execute code on (-e) and filter (-c) the input (this is done
before LOOKUPS are processed, if any). If datum is an object, then a
shortcut is <key>. To remove a key, use this.<key> = undefined. For array
items, use this[<index>] = 42.

-e CODE
Execute the given code on the input. If input is an array, then
each item of the array is processed separately (use -A to
override).

-c CODE
Filter the input with CODE. If CODE returns false-y, then the item
is filtered out. If input is an array, then each item of the array
is processed separately (use -A to override).

Finally, if LOOKUP arguments are given, these are extracted from the
JSON. By default . is used as a separator for nested object lookup. This
can be overridden:

-D DELIM
Delimiter char between LOOKUPS (default is '.'). For example: $
echo '{"a.b": {"b": 1}}' | json -D / a.b/b

An alternative to lookups is to output the keys of the input object:

-k, --keys
Output the input object's keys.

json can be restricting to just validating its input, i.e. processing and
output of the input is skipped:

--validate
Just validate the input, no processing or output of the JSON
content.

By default json outputs in "jsony" mode. Basically this is JSON output,
with the exception that a single string output value is emitted without
the quotes. The intention here is to be of most use to the UNIX
command-line. Other output formats are supported:

-o MODE, --output MODE
Specify an output mode. One of jsony (the default; JSON, if a
single string then quotes are elided), json (JSON output, 2-space
indent), json-N (JSON output, N-space indent, e.g. 'json-4'), or
inspect (node.js util.inspect output).

-i Shortcut for -o inspect.

-j Shortcut for -o json.

EXAMPLES

A typical JSON REST API response:


$ curl -s http://ifconfig.me/all.json
{"connection":"","ip_addr":"216.57.203.67","lang":"","remote_host":...


Nice output by default:


$ curl -s http://ifconfig.me/all.json | json
{
"connection": "",
"ip_addr": "201.73.103.12",
"lang": "",
"remote_host": "",
"user_agent": "curl/7.23.1 (i386-sun-solaris2.11) libcurl/7.23.1 OpenSSL/0.9.8w zlib/1.2.3 libidn/1.23 libssh2/1.2.2",
"charset": "",
"port": "63713",
"via": "",
"forwarded": "",
"mime": "*/*",
"keep_alive": "",
"encoding": ""
}


Say you just want to extract one value:


$ curl -s http://ifconfig.me/all.json | json ip_addr
201.73.103.12


Or, looking at the node.js project https://github.com/joyent/node using
the Github API:


$ curl -s https://api.github.com/repos/joyent/node | json open_issues
517


If you use curl -i to get HTTP headers (because perhaps they contain
relevant information), json will skip the HTTP headers automatically:


$ curl -is https://api.github.com/repos/joyent/node | json
HTTP/1.1 200 OK
Server: nginx/1.0.13
Date: Tue, 24 Jul 2012 04:01:08 GMT
Content-Type: application/json; charset=utf-8
Connection: keep-alive
Status: 200 OK
ETag: "1a21d980a01768dde42145ce2b58694c"
X-RateLimit-Remaining: 4997
Content-Length: 1513
Cache-Control: public, max-age=60
Vary: Accept
X-RateLimit-Limit: 5000
Last-Modified: Tue, 24 Jul 2012 03:50:11 GMT

{
"master_branch": "master",
"has_issues": true,
"has_downloads": false,
"homepage": "http://nodejs.org/",
"html_url": "https://github.com/joyent/node",
...


Or, say you are stuck with the headers in your pipeline, 'json -H' will
drop HTTP headers:


$ curl -is https://api.github.com/repos/joyent/node | json -H forks
2158


Here is an example that shows indexing a list. (The given "lookup"
argument is basically JavaScript code appended, with '.' if necessary, to
the JSON data and eval'd.)


$ curl -s https://api.github.com/legacy/repos/search/nodejs \
| json 'repositories[2].name'
socket.io


Having the quote to avoid shell interpretation of '[' is annoying, so
json allows a special case for an integer lookup:


$ curl -s https://api.github.com/legacy/repos/search/nodejs \
| json 'repositories.2.name'
socket.io


Array processing with -a
json includes the -a (aka --array) option for processing each element of
an input JSON array independently and using tabular output. Let's first
get a list of open node.js issues (note that this is a subset because of
GH API pagination http://developer.github.com/v3/#pagination):


$ curl -s https://api.github.com/repos/joyent/node/issues?state=open\&per_page=100
[
{
"number": 3757,
"html_url": "https://github.com/joyent/node/issues/3757",
"body": "Fix #3756.\n\nReview, please: @TooTallNate",
"milestone": null,
"user": {
"gravatar_id": "73a2b24daecb976af81e010b7a3ce3c6",
"login": "isaacs",
"avatar_url": "https://secure.gravatar.com/avatar/73a2b24dae...
...


We can then print a table with just some fields as follows:


$ curl -s https://api.github.com/repos/joyent/node/issues?state=open\&per_page=100 \
| json -a comments number title
0 3757 readline: Remove event listeners on close
0 3756 readline: No way to completely unhook interface from input/output
1 3755 node-v0.6.20 hello example segfaults on RaspberryPi (w/Arch + bash)
0 3753 Prohibit same listeners in EventEmitter. Closes #964.
1 3752 Auto-detect hardfloat eabi and armv7 variables on ARM based on compiler
3 3751 persistent REPL history
0 3749 glibc errors on SheevaPlug / Debian Squeeze
...


Ultimately this can be useful for then using other command-line tools.
For example, we could get the list of top-five most commented open node
issues:


$ curl -s https://api.github.com/repos/joyent/node/issues?state=open\&per_page=100 \
| json -a comments number title | sort -n | tail -5
9 3510 Automatically `.toString()` functions in REPL.
11 3668 JSON documentation index listing
12 3624 Add a return value to Buffer.write* methods that returns the ...
12 3655 defer dgram listening event
14 3613 Connections closed by node stay permanently in FIN_WAIT2


Or get a breakdown by ISO language code of the recent tweets mentioning
"nodejs":


$ curl -s http://search.twitter.com/search.json?q=nodejs\&rpp=100 \
| json results | json -a iso_language_code | sort | uniq -c | sort
1 es
1 no
1 th
4 ru
12 ja
23 pt
58 en


The -d option can be used to specify a delimiter:


$ curl -s https://api.github.com/repos/joyent/node/issues?state=open \
| json -a created_at number title -d,
2012-07-24T03:45:03Z,3757,readline: Remove event listeners on close
2012-07-24T03:32:10Z,3756,readline: No way to completely unhook inte...
2012-07-23T21:17:50Z,3755,node-v0.6.20 hello example segfaults on Ra...
2012-07-22T16:17:49Z,3753,Prohibit same listeners in EventEmitter. C...
2012-07-22T13:43:40Z,3752,Auto-detect hardfloat eabi and armv7 varia...

Grouping

You can use the '-g' or '--group' option to group adjacent objects into
an array of those objects; or to concatenate adjacent arrays into a
single array. To attempt to avoid false positives inside JSON strings,
adjacent elements must have either no whitespace separation or at least a
newline separation. Examples:


$ echo '{"a":1}{"b":2}' | json -g # group into array of objects
[
{
"a": 1
},
{
"b": 2
}
]
$ echo '[1,2][3,4]' | json -g # concantenate into one array
[
1,
2,
3,
4
]


This can be useful when processing a number of JSON files, e.g.:


$ cat my_data/*.json | json -g ...


Or when composing multiple JSON API response, e.g. this somewhat
contrived search for node.js bugs mentioning "tty" or "windows":


$ echo tty windows | xargs -n1 -I{} curl -s \
https://api.github.com/legacy/issues/search/joyent/node/open/{} \
| json -g -a issues | json -g -a number title
623 Non-userfacing native modules should be prefixed with _
861 child_process fails after stdin close
1157 `child_process` module should read / write password prompts
1180 Ctrl+Shift+BS can't be input.
...

Output formatting

You can use the '-o MODE' option (or '--output MODE') to control the
output flavour. By default the output is "jsony" (JSON, except that a
simple string is printed without the quotes):


$ echo '[{"name": "Trent"},{"name": "Ewan"}]' | json
[
{
"name": "Trent"
},
{
"name": "Ewan"
}
]

$ echo '[{"name": "Trent"},{"name": "Ewan"}]' | json '0.name'
Trent

$ echo '[{"name": "Trent"},{"name": "Ewan"}]' | json '0.name' -o jsony
Trent


Or for strict JSON output:


$ echo '[{"name": "Trent"},{"name": "Ewan"}]' | json -o json
[
{
"name": "Trent"
},
{
"name": "Ewan"
}
]


By default this uses a 2-space indent. That can be changed with a "-N"
suffix:


$ echo '[{"name": "Trent"},{"name": "Ewan"}]' | json -o json-4
[
{
"name": "Trent"
},
{
"name": "Ewan"
}
]

$ echo '[{"name": "Trent"},{"name": "Ewan"}]' | json -o json-0
[{"name":"Trent"},{"name":"Ewan"}]


You can get colored (non-JSON) output using node.js's util.inspect
http://nodejs.org/docs/latest/api/all.html#util.inspect:


$ echo '[{"name": "Trent"},{"name": "Ewan"}]' | json -o inspect
[ { name: 'Trent' },
{ name: 'Ewan' } ]

Validation

Since v1.2.0 json will give position information and context for JSON
syntax errors (SyntaxError). This can be handy for validating data and
config files:


$ cat config.json | json
json: error: input is not JSON: Unexpected ',' at line 17, column 5:
, { "name": "smartos64-1.4.7"
....^
{
"use-proxy": false
...
$ echo $?
1


Processing and output of the input JSON can be suppressed with the
--validate option:


$ cat config.json | json --validate
json: error: input is not JSON: Unexpected ',' at line 17, column 5:
, { "name": "smartos64-1.4.7"
....^


Together with the -q you can get silent, exit-status-only, JSON
validation:


$ cat config.json | json --validate -q
$ echo $?
1

Executing code snippets on input

You can use the -e CODE option to execute small code snippets to massage
the input data. Some examples (generally use this.<key> to refer to a
key):


$ echo '{"foo": "bar"}' | json -e 'this.foo="baz"'
{"foo":"baz"}


Or omit the this. as a shortcut:


$ echo '{"foo": "bar"}' | json -e 'foo="baz"'
{"foo":"baz"}
$ echo '{"age": 38}' | json -e 'age++'
{"age":39}


Set a key to undefined to remove it:


$ echo '{"one": 1, "two": 2}' | json -e 'this.one=undefined'
{"two":2}


If the input is an array, then -e will automatically process each element
separately (use -A to override this):


$ echo '[{"name":"trent", "age":38}, {"name":"ewan", "age":4}]' \
| json -e 'age++'
[
{
"name": "trent",
"age": 39
},
{
"name": "ewan",
"age": 5
}
]


Filtering with '-c'
You can use the -c CODE option to filter the input:


$ echo '{"name":"trent", "age":38}' | json -c 'age>21'
{
"name": "trent",
"age": 38
}
$ echo '{"name":"trent", "age":38}' | json -c 'age==16'
$


If the input is an array, then -c will automatically process each element
separately (use -A to override this):


$ echo '[{"name":"trent", "age":38}, {"name":"ewan", "age":4}]' \
| json -c 'age>21'
[
{
"name": "trent",
"age": 38
}
]

COMPATIBILITY

This is json version 4. The major version is incremented when there is a
backward incompatible change.

+o v4: Made "auto-arrayification" require an explicit '-g' or '--group'
option to prefer that implicit processing never magically fix
otherwise invalid JSON. The feature is now called grouping.

+o v3: Cleaned up json and "jsony" output formatting to be more
consistent, especially for array processing.


See the changelog https://github.com/trentm/json/blob/master/CHANGES.md
for full compatibility and change details.

PROJECT & BUGS
json is written in JavaScript and requires node.js (node). The project
lives at https://github.com/trentm/json and is published to npm as
"jsontool" ("json" was already taken, boo).

+o README, Install notes: https://github.com/trentm/json#readme

+o Report bugs to https://github.com/trentm/json/issues.

+o See the full changelog at:
https://github.com/trentm/json/blob/master/CHANGES.md

LICENSE

MIT License (see https://github.com/trentm/json/blob/master/LICENSE.txt)

COPYRIGHT

json is Copyright (c) 2012 Trent Mick

July 2012 JSON(1)