JSON-objecten transformeren en opbouwen met jq

JSON uit de praktijk is vaak genest. Met jq kun je binnen een objectconstructor geneste paden benaderen en de structuur tegelijkertijd afvlakken.

Gebruik puntpadnotatie binnen de waarde-expressie van de constructor:

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

Het onderstaande voorbeeld neemt een diep genest gebruikersrecord en produceert een vlak overzicht dat geschikt is voor een CSV-koprij of de body van een API-verzoek.

map(expr) is het jq-equivalent van voor elk: het past expr toe op elk element van een invoerarray en retourneert een nieuwe array met dezelfde lengte.

Belangrijke punten:

• map(expr) is een verkorte schrijfwijze voor [.[] | expr]
• De expressie binnenin kan elk jq-filter zijn — ook objectconstructie
• Combineer dit met select() om eerst te filteren en daarna te transformeren

Het fragment verwerkt een lijst met bestellingen en behoudt alleen de velden die nodig zijn voor een verzendmanifest.

Binnen map kun je nieuwe waarden berekenen, typen omzetten en velden combineren — je hoeft ze niet alleen te kopiëren. Veelgebruikte patronen zijn:

• Stringinterpolatie: "\(.first) \(.last)"
• Rekenkundige bewerking: (.price * 1.2 | round) voor een opslag van 20%
• Voorwaardelijke expressies: if .score >= 90 then "A" else "B" end

Het onderstaande voorbeeld verrijkt een lijst met werknemers door een berekende fullName en een label seniority toe te voegen op basis van het aantal jaren ervaring.

to_entries zet een JSON-object om in een array met paren van {key, value}. Hierdoor kun je arraybewerkingen (map, select, sort) uitvoeren op de velden van een object — iets wat je niet rechtstreeks op een object kunt doen.

Voorbeeldtransformatie:

• Invoer: {"a": 1, "b": 2}
• Uitvoer: [{"key": "a", "value": 1}, {"key": "b", "value": 2}]

De omgekeerde bewerking is from_entries, die de array weer omzet in een object. Samen vormen ze het idioom to_entries | map(...) | from_entries voor transformaties op objectniveau.

Een van de praktischste toepassingen van to_entries is dynamisch bepalen welke sleutels je wilt behouden of verwijderen op basis van de naam van de sleutel zelf — iets wat objectconstructie niet kan wanneer je de sleutelnamen vooraf niet kent.

Patroon:

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

Het onderstaande fragment verwijdert alle sleutels die met een underscore beginnen (interne/private velden) voordat het een configuratieobject doorstuurt naar een externe service.

Met objectconstructie hernoem je sleutels wanneer je hun namen tijdens het schrijven kent. Met to_entries kun je sleutels programmatisch hernoemen — bijvoorbeeld door camelCase om te zetten naar snake_case of door een voorvoegsel toe te voegen.

Werk binnen map het veld .key van elke entry bij en stuur het resultaat daarna door naar from_entries:

• map(.key |= gsub("(?<=[a-z])(?=[A-Z])"; "_") | .key |= ascii_downcase) — camelCase naar snake_case
• map(.key |= "app_" + .) — voeg aan elke sleutel een voorvoegsel toe

Het voorbeeld voegt aan alle namen van omgevingsvariabelen het voorvoegsel APP_ toe om ze vóór injectie in een container van een naamruimte te voorzien.

Het patroon to_entries | map(...) | from_entries komt zo vaak voor dat jq hiervoor een verkorte notatie biedt: with_entries(expr).

Deze is precies equivalent, maar beknopter:

• with_entries(.value |= . * 2) — verdubbel elke numerieke waarde
• with_entries(select(.value != null)) — verwijder sleutels met een null-waarde
• with_entries(.key |= ascii_upcase) — zet alle sleutels om naar hoofdletters

Het fragment verwijdert alle sleutels waarvan de waarde null of een lege tekenreeks is — een veelvoorkomende opschoonstap voordat je een PATCH-verzoek naar een REST-API stuurt.

Transformaties uit de praktijk koppelen meerdere jq-bewerkingen aan elkaar. Een typische pijplijn voor het voorbereiden van een API-payload kan het volgende doen:

1. Filter de invoerarray met map(select(...))
2. Geef elk element een andere vorm met objectconstructie
3. Voeg berekende velden toe
4. Sorteer het resultaat

Het onderstaande voorbeeld leest een lijst met serverstatistieken, behoudt alleen servers met een hoog CPU-gebruik en produceert een compacte waarschuwingspayload die klaar is om met POST naar een webhook te worden gestuurd.

Met jq kun je invoer samenvoegen en objecten construeren die gegevens uit meerdere JSON-bronnen halen met de opteloperator + en variabelen binden met as $var.

Nuttige patronen:

• obj1 + obj2 — voeg twee objecten samen (bij conflicterende sleutels wint de rechterkant)
• --argjson — geef een tweede JSON-document door als variabele
• $ENV — lees omgevingsvariabelen rechtstreeks binnen jq

Het fragment voegt een basisconfiguratie samen met omgevingsspecifieke overschrijvingen — een veelgebruikt patroon voor het beheren van configuratie voor 12-factor-applicaties in shellscripts.

Je hebt de essentiële technieken behandeld voor het een andere vorm geven van JSON met jq:

• Objectconstructie {} — bouw nieuwe objecten door velden uit de invoer te selecteren, hernoemen en berekenen
• map(expr) — pas elke transformatie toe op elk element van een array, inclusief geneste objectconstructie en select() voor filtering
• to_entries / from_entries — zet een object om in een array met paren van {key, value}, zodat je bewerkingen op sleutels en waarden kunt uitvoeren, en zet het daarna weer terug
• with_entries(expr) — de beknopte verkorte notatie voor de volledige pijplijn to_entries → map → from_entries
• Objecten samenvoegen met + en --argjson voor payloads uit meerdere bronnen

Deze bouwstenen kun je combineren: filter met select, geef gegevens een andere vorm met objectconstructie, verrijk ze met berekende velden en koppel alles in één leesbare jq-expressie aan elkaar. Als je deze patronen beheerst, kun je vrijwel elke JSON-payload rechtstreeks in de shell bewerken zonder een apart script in Python of Node te schrijven.