Comment convertir un fichier JSON en CSV ? Méthode et erreurs à éviter

Comprendre la différence entre JSON et CSV

Le JSON peut contenir des objets, des tableaux, des chaînes, des nombres, des booléens et la valeur null. Sa structure peut être imbriquée à plusieurs niveaux.

Le CSV représente généralement une table : chaque ligne correspond à un enregistrement et chaque colonne à un champ. Les valeurs contenant une virgule, un guillemet ou un retour à la ligne doivent être correctement échappées.

Avant de convertir un fichier JSON en CSV, décidez :

• quelle branche du JSON contient les enregistrements ;
• quelles propriétés doivent devenir des colonnes ;
• comment traiter les objets et tableaux imbriqués ;
• comment représenter les valeurs absentes et null ;
• quel séparateur utiliser : virgule, point-virgule ou tabulation.

Le cas le plus simple : un tableau d’objets

La conversion est directe lorsque le JSON contient un tableau d’objets partageant des propriétés similaires :

[
  {
    "id": 1,
    "nom": "Alice",
    "email": "alice@example.com"
  },
  {
    "id": 2,
    "nom": "Bob",
    "email": "bob@example.com"
  }
]

Chaque objet devient une ligne et chaque clé devient une colonne :

id,nom,email
1,Alice,alice@example.com
2,Bob,bob@example.com

Convertir JSON en CSV avec Python

Avec les bibliothèques standard json et csv

Cette méthode ne nécessite aucune installation supplémentaire. Elle vérifie que le fichier contient bien un tableau d’objets, récupère l’ensemble des clés et écrit le CSV en UTF-8.

import csv
import json

with open("input.json", "r", encoding="utf-8") as f:
    data = json.load(f)

if not isinstance(data, list) or not all(isinstance(row, dict) for row in data):
    raise ValueError("Le JSON doit être un tableau d’objets.")

fieldnames = []
for row in data:
    for key in row:
        if key not in fieldnames:
            fieldnames.append(key)

def csv_value(value):
    if isinstance(value, (dict, list)):
        return json.dumps(value, ensure_ascii=False)
    if value is None:
        return ""
    return value

with open("output.csv", "w", encoding="utf-8", newline="") as f:
    writer = csv.DictWriter(
        f,
        fieldnames=fieldnames,
        extrasaction="ignore"
    )
    writer.writeheader()

    for row in data:
        writer.writerow({
            key: csv_value(row.get(key))
            for key in fieldnames
        })

Dans cet exemple, les clés absentes produisent une cellule vide, tandis que les objets et tableaux imbriqués sont conservés sous forme de texte JSON. L’option ensure_ascii=False préserve les accents.

L’ouverture du fichier CSV avec newline="" est recommandée lors de l’utilisation du module csv.

Convertir JSON en CSV avec jq

jq est adapté aux conversions rapides en ligne de commande, notamment lorsque les colonnes sont connues à l’avance. Le filtre @csv gère l’échappement des valeurs CSV.

jq -r '
  (["id", "nom", "email"] | @csv),
  (.[] | [.id, .nom, .email] | @csv)
' input.json > output.csv

L’option -r produit du CSV brut au lieu de chaînes JSON entourées de guillemets.

Si les enregistrements se trouvent dans une structure imbriquée, sélectionnez d’abord le tableau concerné :

jq -r '
  (["id", "nom"] | @csv),
  (.data.items[] | [.id, .nom] | @csv)
' input.json > output.csv

Convertir JSON en CSV avec pandas

pandas convient aux fichiers qui nécessitent un nettoyage, une transformation ou une analyse avant export.

Tableau JSON classique

import pandas as pd

df = pd.read_json("input.json", orient="records")
df.to_csv(
    "output.csv",
    index=False,
    encoding="utf-8"
)

index=False évite d’ajouter au CSV une colonne artificielle contenant l’index pandas.

Fichier JSON Lines

Si le fichier contient un objet JSON par ligne, utilisez lines=True :

import pandas as pd

df = pd.read_json("input.json", lines=True)
df.to_csv("output.csv", index=False, encoding="utf-8")

Pour les structures particulières, choisissez l’orientation adaptée, par exemple records, index, columns, split, values ou table.

Gérer les données JSON imbriquées

Un JSON contenant des objets ou tableaux imbriqués ne correspond pas automatiquement à une table simple :

[
  {
    "id": 1,
    "nom": "Alice",
    "adresse": {
      "ville": "Paris",
      "pays": "France"
    },
    "tags": ["client", "premium"]
  }
]

Conserver les structures dans une cellule

id,nom,adresse,tags
1,Alice,"{""ville"": ""Paris"", ""pays"": ""France""}","[""client"", ""premium""]"

Cette solution conserve l’information, mais le contenu est moins pratique à filtrer dans un tableur.

Aplatir les objets

id,nom,adresse.ville,adresse.pays
1,Alice,Paris,France

Cette approche facilite l’analyse, à condition de définir une convention de nommage cohérente.

Créer plusieurs fichiers CSV

Lorsque les tableaux imbriqués contiennent plusieurs éléments par enregistrement, créez par exemple :

• clients.csv pour les informations principales ;
• adresses.csv pour les adresses ;
• client_tags.csv pour les relations entre clients et tags.

Les erreurs à éviter

Supposer que tout JSON est directement tabulaire

Un fichier JSON peut être un objet unique, un tableau de valeurs simples ou une structure profondément imbriquée. Identifiez d’abord la collection qui doit devenir l’ensemble des lignes.

Remplacer simplement les caractères

Une substitution des virgules, deux-points ou accolades ne constitue pas une conversion fiable. Une virgule peut faire partie d’une valeur, et les guillemets doivent respecter les règles d’échappement du CSV.

Oublier les guillemets et les retours à la ligne

Une valeur contenant une virgule, un retour à la ligne ou un guillemet doit être entourée et échappée correctement. Un guillemet interne est généralement représenté par deux guillemets consécutifs.

Perdre les données imbriquées

Décidez explicitement si les objets et tableaux doivent être conservés comme texte, aplatis ou répartis dans plusieurs fichiers.

Confondre valeur absente, null et chaîne vide

Une cellule vide peut correspondre à une propriété absente, à null, à une chaîne vide ou à une donnée indisponible. Documentez la règle utilisée.

Perdre les zéros initiaux

Les codes postaux, numéros de téléphone et identifiants comme 00123 doivent être traités comme des chaînes lorsque les zéros ont une signification.

Modifier les dates et les nombres

Certains outils convertissent automatiquement les dates, les décimales ou les grands nombres. Vérifiez les types après lecture et après export.

Oublier l’encodage

Utilisez généralement UTF-8 pour préserver les accents, puis vérifiez que le logiciel destinataire interprète correctement cet encodage.

Ajouter l’index pandas par erreur

Avec pandas, utilisez index=False pour éviter une colonne supplémentaire :

df.to_csv("output.csv", index=False)

Ne pas valider le JSON

Un JSON invalide peut provoquer une erreur de décodage. Vérifiez également les clés dupliquées, dont l’interprétation peut varier selon les logiciels.

Contrôler le fichier CSV après conversion

• Vérifiez que le nombre de lignes correspond aux enregistrements attendus.
• Contrôlez la présence et l’ordre des colonnes.
• Testez les accents et l’encodage.
• Vérifiez les champs contenant des virgules, guillemets ou retours à la ligne.
• Comparez les valeurs absentes, null et vides.
• Contrôlez les identifiants et les zéros initiaux.
• Ouvrez le fichier avec le logiciel qui l’utilisera réellement.
• Comparez quelques lignes avec le JSON d’origine.

Quelle méthode choisir ?

• Conversion ponctuelle et structure simple : Python standard ou jq.
• Sélection précise de champs en ligne de commande : jq.
• Nettoyage, transformation ou données volumineuses : pandas, en surveillant les types et la mémoire.
• JSON imbriqué : définissez d’abord le schéma CSV cible.