Tutorial jq: filtra e trasforma JSON

jq è lo strumento standard da riga di comando per affettare, filtrare e trasformare JSON. Trasforma one-liner in un potente linguaggio di query per risposte API, file di log e configurazioni. Questo tutorial copre l'installazione, i filter centrali che userai ogni giorno, e una raccolta di recipe da copia-incolla per i compiti più comuni del mondo reale.

Cos'è jq?

jq legge JSON da un file o dallo standard input, applica un filter, e scrive JSON (o testo grezzo) sullo standard output. Pretty-printa di default e non manda mai i tuoi dati da nessuna parte —— è un binario locale, ideale per payload sensibili.

Installare jq

# macOS
brew install jq

# Debian / Ubuntu
sudo apt-get install jq

# Windows (winget o choco)
winget install jqlang.jq

# Verifica
jq --version

Il filter identity: pretty-print di qualsiasi cosa

Il filter più semplice, ., restituisce l'input invariato —— il che rende jq un formatter istantaneo:

# Pretty-print di un file
jq . data.json

# Pretty-print di una risposta curl
curl -s https://api.example.com/users | jq .

# Al contrario: minify (output compatto)
jq -c . data.json

Selezionare i campi

Entra negli oggetti con .key, e negli array con []:

echo '{"user":{"name":"Ada","age":36}}' | jq '.user.name'
# "Ada"

# Tutti gli elementi di un array
echo '[{"id":1},{"id":2}]' | jq '.[]'
# {"id":1}
# {"id":2}

# Un campo da ogni elemento dell'array
echo '[{"id":1,"name":"Ada"},{"id":2,"name":"Bob"}]' | jq '.[].name'
# "Ada"
# "Bob"

# Togli le virgolette JSON con -r (raw output)
jq -r '.[].name' users.json

Filtrare con select

# Tieni solo gli oggetti che soddisfano una condizione
echo '[{"name":"Ada","active":true},{"name":"Bob","active":false}]' \
  | jq '.[] | select(.active == true)'
# {"name":"Ada","active":true}

# Confronto numerico
jq '.[] | select(.age > 30)' users.json

Trasformare con map e costruzione di oggetti

# Rimodella ogni elemento in un nuovo oggetto
echo '[{"id":1,"name":"Ada","email":"a@x.com"}]' \
  | jq 'map({ userId: .id, label: .name })'
# [{"userId":1,"label":"Ada"}]

# Tira fuori una lista piatta di valori
jq '[.[].email]' users.json     # ["a@x.com", ...]

# Concatena filter con |
jq '.items | map(.price) | add' order.json   # somma di tutti i prezzi

Recipe comuni

Rimodellare oggetti: to_entries / from_entries

I due trasformatori di forma di oggetto più utili in jq:

# Rinomina ogni key (qui in minuscolo)
echo '{"Name":"Ada","Active":true}' \
  | jq 'with_entries(.key |= ascii_downcase)'
# → {"name":"Ada","active":true}

# Scarta le key il cui valore è null
jq 'with_entries(select(.value != null))' file.json

# Oggetto ⇄ array di coppie
jq 'to_entries' file.json     # → [{"key":"name","value":"Ada"}, ...]
jq 'from_entries' pairs.json  # → {"name":"Ada", ...}

Interpolazione e formati di output: \(.x), @csv, @json, @base64

jq ha interpolazione di stringhe e format string integrate per trasformare JSON in altri formati:

# Interpolazione di stringa dentro una stringa fra virgolette
jq -r '"\(.user) bought \(.items|length) items"' order.json

# Una riga CSV per oggetto
jq -r '.[] | [.id, .name, .total] | @csv' orders.json

# JSON inline per le shell (literal di stringa escaped)
jq -r '.user | @json' record.json

# Codifica un valore in Base64 (utile per token / data URI)
jq -r '.payload | @base64' message.json
# Lato decodifica: jq accetta @base64d nelle versioni più recenti

Validare JSON con jq

Visto che jq esce con codice diverso da zero su input non valido, jq empty file.json è un controllo di validità pulito per script e CI —— vedi Come validare JSON per altri approcci di validazione.

Quando uno strumento browser è più veloce

jq brilla in script e pipeline, ma per qualcosa di occasionale —— formattare una risposta incollata, ispezionare una struttura sconosciuta, o riparare JSON rotto —— uno strumento browser non richiede installazione né escape della shell:

• JSON Fix —— formatta e ripara JSON in un passo
• JSON Viewer —— esplora risposte grandi come un albero pieghevole
• Come formattare JSON —— formattazione in codice e da riga di comando

Domande frequenti

Come faccio pretty-print di JSON con jq?

Esegui jq . file.json —— il filter identity . restituisce l'input e jq lo formatta di default. Usa -c per output compatto.

Come estraggo un singolo campo con jq?

Usa un filter di path come jq '.data.token', e aggiungi -r per output grezzo se vuoi il valore senza le virgolette.

Come filtro un array JSON con jq?

Itera con .[] e applica select(), ad es. jq '.[] | select(.active == true)'.

jq può validare JSON?

Sì —— jq empty file.json parsa l'input ed esce con codice diverso da zero se è non valido, il che lo rende pratico in CI. Per i dettagli vedi Come validare JSON.

Continua a leggere

• Come formattare JSON —— jq, JavaScript, Python e formattazione nel browser
• Come minificare JSON —— output compatto con jq -c e oltre
• Come validare JSON —— incluso jq empty in CI
• JSON Viewer —— alternativa nel browser per esplorare JSON