Transformer et construire des objets JSON avec jq

Le JSON brut provenant d’API ou de fichiers de journal a rarement exactement la structure dont vous avez besoin. Vous pouvez recevoir un objet volumineux alors que seuls certains champs vous intéressent, ou devoir renommer des clés, aplatir des structures imbriquées ou construire une nouvelle charge utile à envoyer à un autre service.

jq est un processeur JSON léger et puissant en ligne de commande qui permet d’effectuer ces transformations dans une seule chaîne de traitement. Dans cette leçon, vous apprendrez trois techniques fondamentales pour remodeler les données :

• Construction d’objet — créer un nouvel objet JSON à partir de zéro
• map — appliquer une transformation à chaque élément d’un tableau
• to_entries / from_entries — traiter les paires clé-valeur d’un objet comme un tableau afin de pouvoir les filtrer et les reconstruire

Tous les exemples supposent que jq est installé (apt install jq / brew install jq).

La fonctionnalité jq la plus fondamentale est la construction d’objets : entourer des expressions de {} pour créer un nouvel objet JSON. Vous choisissez les champs à inclure et le nom à leur donner.

Syntaxe :

• { newKey: .existingField } — renommer un champ
• { name, age } — forme abrégée lorsque la nouvelle clé correspond au nom du champ
• { total: (.price * .qty) } — calculer une valeur directement dans l’expression

L’extrait ci-dessous lit un produit JSON et produit une structure plus concise contenant un champ subtotal calculé.

Le JSON réel est souvent imbriqué. jq vous permet d’accéder à des chemins imbriqués dans un constructeur d’objet, tout en aplatissant la structure.

Utilisez la notation par chemin avec des points dans l’expression de valeur du constructeur :

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

L’exemple ci-dessous prend un enregistrement utilisateur profondément imbriqué et produit un résumé à plat adapté à une ligne d’en-tête CSV ou au corps d’une requête d’API.

map(expr) est l’équivalent jq d’une boucle pour chaque élément : cette fonction applique expr à chaque élément d’un tableau d’entrée et renvoie un nouveau tableau de même longueur.

Points essentiels :

• map(expr) est une forme abrégée de [.[] | expr]
• L’expression interne peut être n’importe quel filtre jq, y compris une construction d’objet
• Combinez-la avec select() pour filtrer avant de transformer

L’extrait traite une liste de commandes en ne conservant que les champs nécessaires à un bordereau d’expédition.

Dans map, vous pouvez calculer de nouvelles valeurs, convertir des types et combiner des champs, et pas seulement les copier. Voici quelques schémas courants :

• Interpolation de chaînes : "\(.first) \(.last)"
• Arithmétique : (.price * 1.2 | round) pour une majoration de 20 %
• Conditions : if .score >= 90 then "A" else "B" end

L’exemple ci-dessous enrichit une liste d’employés en ajoutant un fullName calculé et une étiquette seniority basée sur le nombre d’années d’expérience.

to_entries convertit un objet JSON en un tableau de paires {key, value}. Cela permet d’appliquer des opérations sur les tableaux (map, select, sort) aux champs d’un objet, ce qui n’est pas possible directement sur un objet.

Exemple de transformation :

• Entrée : {"a": 1, "b": 2}
• Sortie : [{"key": "a", "value": 1}, {"key": "b", "value": 2}]

L’opération inverse est from_entries, qui reconvertit ce tableau en objet. Ensemble, ces fonctions constituent l’idiome to_entries | map(...) | from_entries pour transformer des objets.

L’un des usages les plus pratiques de to_entries consiste à filtrer dynamiquement les clés à conserver ou à supprimer en fonction du nom de la clé lui-même, ce que la construction d’objet ne permet pas lorsque les noms des clés ne sont pas connus à l’avance.

Schéma :

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

L’extrait ci-dessous supprime toutes les clés qui commencent par un trait de soulignement (champs internes ou privés) avant de transmettre un objet de configuration à un service externe.

La construction d’objet renomme les clés lorsque vous connaissez leur nom au moment de l’écriture. to_entries vous permet de renommer les clés par programmation, par exemple en convertissant camelCase en snake_case ou en ajoutant un préfixe.

Dans map, vous mettez à jour le champ .key de chaque entrée, puis vous utilisez un canal vers from_entries :

• map(.key |= gsub("(?<=[a-z])(?=[A-Z])"; "_") | .key |= ascii_downcase) — convertir camelCase en snake_case
• map(.key |= "app_" + .) — ajouter un préfixe à chaque clé

L’exemple préfixe tous les noms de variables d’environnement par APP_ afin de les regrouper dans un espace de noms avant leur injection dans un conteneur.

Le schéma to_entries | map(...) | from_entries est si courant que jq fournit une forme abrégée : with_entries(expr).

Elle est strictement équivalente, mais plus concise :

• with_entries(.value |= . * 2) — doubler chaque valeur numérique
• with_entries(select(.value != null)) — supprimer les clés dont la valeur est nulle
• with_entries(.key |= ascii_upcase) — convertir toutes les clés en majuscules

L’extrait supprime toutes les clés dont la valeur est null ou une chaîne vide, une étape de nettoyage courante avant l’envoi d’une requête PATCH à une API REST.

Les transformations réelles enchaînent plusieurs opérations jq. Une chaîne de traitement typique pour préparer une charge utile d’API peut :

1. Filtrer le tableau d’entrée avec map(select(...))
2. Remodeler chaque élément avec une construction d’objet
3. Ajouter des champs calculés
4. Trier le résultat

L’exemple ci-dessous lit une liste de mesures de serveurs, ne conserve que les serveurs dont l’utilisation du CPU est élevée et produit une charge utile d’alerte compacte prête à être envoyée par POST à un webhook.

jq peut fusionner des entrées et construire des objets provenant de plusieurs sources JSON à l’aide de l’opérateur d’addition + et de la liaison de variables avec as $var.

Schémas utiles :

• obj1 + obj2 — fusionner deux objets (la valeur de droite l’emporte en cas de conflit entre clés)
• --argjson — transmettre un deuxième document JSON sous forme de variable
• $ENV — lire directement les variables d’environnement dans jq

L’extrait fusionne une configuration de base avec des remplacements propres à l’environnement, un schéma courant pour gérer la configuration d’applications selon les principes des applications à douze facteurs dans les scripts shell.

Vous disposez de l’objet JSON suivant et devez supprimer toutes les clés dont la valeur est inférieure à 0, afin de produire un nouvel objet contenant uniquement des valeurs positives ou nulles. Quelle expression jq permet d’obtenir ce résultat ?

Entrée : {"a": 10, "b": -3, "c": 0, "d": 5}

Vous avez étudié les techniques essentielles pour remodeler du JSON avec jq :

• Construction d’objet {} — créer de nouveaux objets en sélectionnant, renommant et calculant des champs à partir d’une entrée
• map(expr) — appliquer n’importe quelle transformation à chaque élément d’un tableau, notamment une construction d’objet imbriquée et select() pour le filtrage
• to_entries / from_entries — convertir un objet en tableau de paires {key, value}, ce qui permet d’effectuer des opérations sur les clés et les valeurs, puis reconvertir le tableau
• with_entries(expr) — forme abrégée et concise de la chaîne complète to_entries → map → from_entries
• Fusion d’objets avec + et --argjson pour créer des charges utiles provenant de plusieurs sources

Ces éléments de base se combinent : filtrez avec select, remodelez avec la construction d’objets, enrichissez avec des champs calculés et enchaînez le tout dans une seule expression jq lisible. La maîtrise de ces schémas vous permet de manipuler pratiquement n’importe quelle charge utile JSON directement dans le shell, sans écrire de script dédié en Python ou Node.