Managing JSON with jq

Update: I’ve released a workshopper-style interactive tutorial covering the basics of jq. Just getting started? Check it out!


For the longest time, I assumed that the way to debug API JSON was to pipe it through a pretty printer like python’s json.tool. Not the most concise solution, but it cleans up nicely enough:

$ curl api.app.com/users | python -mjson.tool

[
  {
    "email": "chico@ma.rx", 
    "id": 41, 
    "role": "user"
  }, 
  {
    "email": "harpo@ma.rx", 
    "id": 42, 
    "role": "user"
  }, 
  {
    "email": "groucho@ma.rx", 
    "id": 43, 
    "role": "admin"
  }
]

But oh! How wrong I’ve been.

If it isn’t the greatest thing since sliced bread (at least for debugging JSON APIs), Stephen Dolan‘s jq has to be pretty close. Pretty print? Got it.

$ curl api.app.com/users | jq .

Selectors? Done.

$ curl api.app.com/users | jq '.[0] | { id, email }'

Filter, map, reduce? Check, check, check.

$ curl api.app.com/users | jq '.[] | select(.id == 42)'
$ curl api.app.com/users | jq 'map({ id, email })'
$ curl api.app.com/users | jq 'reduce .[] as $item (0; . + $item.id)'

The list goes on and on.

Let’s keep in touch

Get noise-free updates on software, product, and process.

Hey, I'm RJ: digital entomologist and intermittent micropoet, writing from the beautiful Rose City.