Trasformare e costruire oggetti JSON con jq

Il JSON grezzo proveniente dalle API o dai file di log raramente ha esattamente la struttura necessaria. Potrebbe ricevere un oggetto di grandi dimensioni ma aver bisogno solo di alcuni campi, oppure dover rinominare chiavi, appiattire strutture annidate o creare un payload completamente nuovo da inviare a un altro servizio.

jq è un potente processore JSON leggero da riga di comando, che rende possibili queste trasformazioni in un'unica pipeline. In questa lezione apprenderà le tre tecniche fondamentali per ristrutturare i dati:

• Costruzione di oggetti — crea un nuovo oggetto JSON da zero
• map — applica una trasformazione a ogni elemento di un array
• to_entries / from_entries — tratta le coppie chiave-valore di un oggetto come un array, così da poterle filtrare e ricostruire

Tutti gli esempi presuppongono che jq sia installato (apt install jq / brew install jq).

La funzionalità più fondamentale di jq è la costruzione di oggetti: racchiudere le espressioni tra {} per creare un nuovo oggetto JSON. Può scegliere quali campi includere e come denominarli.

Sintassi:

• { newKey: .existingField } — rinomina un campo
• { name, age } — forma abbreviata quando la nuova chiave corrisponde al nome del campo
• { total: (.price * .qty) } — calcola un valore direttamente nell'espressione

Il frammento seguente legge il JSON di un prodotto e genera una struttura più essenziale con un campo subtotal calcolato.

Il JSON del mondo reale è spesso annidato. jq consente di accedere ai percorsi annidati all'interno di un costruttore di oggetti, appiattendo contemporaneamente la struttura.

Utilizzi la notazione con percorso puntato nell'espressione del valore del costruttore:

• { city: .address.city }
• { lat: .location.coords.lat }

L'esempio seguente prende un record utente profondamente annidato e produce un riepilogo piatto, adatto a una riga di intestazione CSV o al corpo di una richiesta API.

map(expr) è l'equivalente jq di un for-each: applica expr a ogni elemento di un array in input e restituisce un nuovo array della stessa lunghezza.

Punti chiave:

• map(expr) è una forma abbreviata di [.[] | expr]
• L'espressione interna può essere qualsiasi filtro jq, inclusa la costruzione di oggetti
• Può essere concatenata con select() per filtrare prima della trasformazione

Il frammento elabora un elenco di ordini, mantenendo solo i campi necessari per un documento di spedizione.

All'interno di map può calcolare nuovi valori, convertire i tipi e combinare i campi, non solo copiarli. Alcuni schemi comuni sono:

• Interpolazione di stringhe: "\(.first) \(.last)"
• Aritmetica: (.price * 1.2 | round) per un aumento del 20%
• Condizionali: if .score >= 90 then "A" else "B" end

L'esempio seguente arricchisce un elenco di dipendenti aggiungendo un fullName calcolato e un'etichetta seniority basata sugli anni di esperienza.

to_entries converte un oggetto JSON in un array di coppie {key, value}. In questo modo è possibile applicare operazioni sugli array (map, select, sort) ai campi di un oggetto, cosa che non è possibile fare direttamente su un oggetto.

Esempio di trasformazione:

• Input: {"a": 1, "b": 2}
• Output: [{"key": "a", "value": 1}, {"key": "b", "value": 2}]

L'operazione inversa è from_entries, che riconverte l'array in un oggetto. Insieme formano l'idioma to_entries | map(...) | from_entries per le trasformazioni a livello di oggetto.

Uno degli usi più pratici di to_entries consiste nel filtrare dinamicamente le chiavi da conservare o rimuovere in base al nome della chiave stessa, cosa che la costruzione di oggetti non consente quando i nomi delle chiavi non sono noti in anticipo.

Schema:

• to_entries | map(select(.key | test("regex"))) | from_entries
• to_entries | map(select(.key != "secret")) | from_entries

Il frammento seguente rimuove tutte le chiavi che iniziano con un carattere di sottolineatura (campi interni/privati) prima di inoltrare un oggetto di configurazione a un servizio esterno.

La costruzione di oggetti rinomina le chiavi quando i loro nomi sono noti al momento della scrittura. to_entries consente di rinominare le chiavi in modo programmatico, ad esempio convertendo camelCase in snake_case o aggiungendo un prefisso.

All'interno di map aggiorna il campo .key di ogni voce, quindi usa una pipe verso from_entries:

• map(.key |= gsub("(?<=[a-z])(?=[A-Z])"; "_") | .key |= ascii_downcase) — da camelCase a snake_case
• map(.key |= "app_" + .) — aggiunge un prefisso a ogni chiave

L'esempio aggiunge il prefisso APP_ a tutti i nomi delle variabili d'ambiente, così da creare uno spazio dei nomi prima di inserirle in un container.

Lo schema to_entries | map(...) | from_entries è così comune che jq fornisce una forma abbreviata: with_entries(expr).

È esattamente equivalente, ma più conciso:

• with_entries(.value |= . * 2) — raddoppia ogni valore numerico
• with_entries(select(.value != null)) — rimuove le chiavi con valore null
• with_entries(.key |= ascii_upcase) — converte tutte le chiavi in maiuscolo

Il frammento rimuove tutte le chiavi il cui valore è null o una stringa vuota, un'operazione di pulizia comune prima di inviare una richiesta PATCH a un'API REST.

Le trasformazioni reali concatenano più operazioni jq. Una pipeline tipica per preparare un payload API potrebbe:

1. Filtrare l'array in input con map(select(...))
2. Ristrutturare ogni elemento con la costruzione di oggetti
3. Aggiungere campi calcolati
4. Ordinare il risultato

L'esempio seguente legge un elenco di metriche dei server, mantiene solo i server con un utilizzo elevato della CPU e produce un payload compatto per gli avvisi, pronto per essere inviato con POST a un webhook.

jq può unire gli input e costruire oggetti che attingono a più origini JSON usando l'operatore di addizione + e il binding di variabili con as $var.

Schema utili:

• obj1 + obj2 — unisce due oggetti (in caso di conflitto tra chiavi prevale il valore a destra)
• --argjson — passa un secondo documento JSON come variabile
• $ENV — legge direttamente le variabili d'ambiente all'interno di jq

Il frammento unisce una configurazione di base con override specifici per l'ambiente, uno schema comune per gestire la configurazione di applicazioni secondo i principi 12-factor negli script shell.

Ha a disposizione il seguente oggetto JSON e deve rimuovere tutte le chiavi il cui valore è minore di 0, producendo un nuovo oggetto contenente solo valori non negativi. Quale espressione jq svolge correttamente questa operazione?

Input: {"a": 10, "b": -3, "c": 0, "d": 5}

Ha appreso le tecniche essenziali per ristrutturare JSON con jq:

• Costruzione di oggetti {} — crea nuovi oggetti selezionando, rinominando e calcolando i campi dell'input
• map(expr) — applica qualsiasi trasformazione a ogni elemento di un array, inclusa la costruzione di oggetti annidati e select() per il filtraggio
• to_entries / from_entries — converte un oggetto in un array di coppie {key, value}, consentendo operazioni sugli array con chiavi e valori, quindi lo riconverte
• with_entries(expr) — la forma abbreviata della pipeline completa to_entries → map → from_entries
• Unione di oggetti con + e --argjson per payload provenienti da più origini

Questi strumenti si combinano tra loro: filtri con select, ristruttura con la costruzione di oggetti, arricchisce con campi calcolati e concatena tutto in un'unica espressione jq leggibile. Padroneggiando questi schemi può gestire praticamente qualsiasi payload JSON direttamente nella shell, senza scrivere uno script dedicato in Python o Node.