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.


How-Tos

Practical tutorials and hands-on guides

Read all

Let’s keep in touch

Reach out on Twitter or subscribe for (very) occasional updates.

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