Mastering JSON Parsing with jq: A Command-Line Power Tool for Developers

Parsing JSON with jq is a great way to manipulate and extract data from JSON documents right from the command line. jq is a lightweight and flexible command-line JSON processor that is designed for parsing, filtering, transforming JSON data according to its compact syntax.

JQ resembles sed for text and awk for structured data in that it provides functions to traverse JSON structures, access specific fields, and do computations. For instance, jq ‘.key’ would yield the value of the key in a JSON object. This makes it invaluable for automation on workflows containing JSON data, like API interactions or config file processing, thanks to its ability to deal with deeply nested structures, arrays, and conditional logic

1. Installation and Setup

If you haven’t installed jq yet, follow these instructions:

• Windows: Use Chocolatey or download the .exe file from the jq releases page.
• Linux: Use your package manager

# Debian/Ubuntu
sudo apt install jq
# CentOS/RHEL
sudo yum install jq
# Fedora
sudo dnf install jq

• macOS: Use Homebrew

brew install jq

Once installed, you can check the installation by running:

jq --version

2. Basic Syntax and Simple Queries

2.1 Basic Syntax

Create a file calles sample.json and open your terminal in the same directory

The standard command structure is:

jq '<filter>' <file.json>

open sample.json and paste this content

{
  "name": "Alice",
  "age": 30,
  "location": {
    "city": "Wonderland",
    "zipcode": "12345"
  },
  "friends": [
    {"name": "Bob", "age": 25},
    {"name": "Carol", "age": 27}
  ]
}

2.2 Simple Queries

• Show the Entire JSON Structure:

jq . sample.json

• Access a Specific Key:

jq '.name' sample.json 

Output:

"Alice"

• Access Nested Keys:

jq '.location.city' sample.json 

Output:

"Wonderland"

• Array Elements:

jq '.friends[0]' sample.json 

Output:

{"name": "Bob", "age": 25}

3. Working with Arrays

• Retrieve All Elements in an Array

To retrieve each friend individually:

jq '.friends[]' sample.json

• Filter Based on Conditions

Retrieve friends older than 25:

jq '.friends[] | select(.age > 25)' sample.json

Output:

{"name": "Carol", "age": 27}

4. Advanced Filters and Modifications

• Multiple Fields Extraction

Retrieve multiple fields at once using {}:

jq '{name: .name, city: .location.city}' sample.json

Output:

{"name": "Alice", "city": "Wonderland"}

• Update JSON Values

To modify a value, use the |= operator:

jq '.age |= 35' sample.json

This will output a modified version where "age": 30 is updated to "age": 35.

• Add or Modify Fields

To add or change a field without modifying the original file:

jq '. + {status: "active"}' sample.json

Output:

{
  "name": "Alice",
  "age": 30,
  "location": {
    "city": "Wonderland",
    "zipcode": "12345"
  },
  "friends": [
    {"name": "Bob", "age": 25},
    {"name": "Carol", "age": 27}
  ],
  "status": "active"
}

• Delete a Field

To remove a field from the JSON output:

jq 'del(.location.zipcode)' sample.json

5. Slicing and Sorting

• Array Slicing

Retrieve the first two friends:

jq '.friends[0:2]' sample.json

• Sorting Arrays

Assuming you have an array of numbers:

[3, 1, 4, 1, 5, 9]

Sort the array:

echo '[3, 1, 4, 1, 5, 9]' | jq 'sort'

• Sorting Objects

Sort friends by age:

jq '.friends | sort_by(.age)' sample.json

This tutorial should have provided a solid foundation in jq! Feel free to practice further by experimenting with more complicated JSON structures.