JSON vs YAML vs CSV : quel format de données utiliser ?

Si vous livrez du logiciel depuis plus de quelques années, vous avez presque certainement tapé chacun de ces trois formats dans un fichier à un moment donné. JSON ruisselle de chaque endpoint REST. YAML est la lingua franca des manifestes Kubernetes, des workflows GitHub Actions, et de la moitié des CLI que vous installez. CSV, c'est ce que le marketing vous envoie par e-mail quand il veut « les données brutes ». Ils semblent interchangeables, et des outils comme Multilities rendent triviale la conversion de l'un à l'autre, mais le fait que vous puissiez convertir ne signifie pas que vous devez choisir au hasard.

Cet article explique comment fonctionne réellement chaque format, où il brille, où il casse, et les règles empiriques que les équipes expérimentées utilisent pour en choisir un. Nous allons regarder le même jeu de données rendu de trois façons afin que les compromis soient concrets plutôt qu'abstraits.

Un modèle mental rapide

Avant de vous noyer dans la syntaxe, gardez ces formats en tête de cette manière :

• JSON est un format de sérialisation pour objets structurés. C'est ce que vous prenez quand une machine doit parler à une autre machine et que les humains ne lisent la sortie qu'occasionnellement.
• YAML est une sorte de surensemble de JSON optimisé pour les humains qui éditent des fichiers de configuration à la main. Il suppose qu'une personne va le faire défiler, le differ et le relire.
• CSV est un format tabulaire. Il suppose que chaque ligne a la même forme, et que le consommateur est probablement un tableur, une commande COPY de base de données, ou un appel rapide pandas read_csv.

JSON : le défaut pour les API et JS

JSON, JavaScript Object Notation, a été extrait de JavaScript au début des années 2000 et normalisé sous RFC 8259. Il a six types primitifs : objet, tableau, chaîne, nombre, booléen et null. C'est tout le vocabulaire. Pas de dates, pas de commentaires, pas de virgules de fin, pas de références. Le minimalisme est intentionnel : tout langage peut analyser le JSON en quelques centaines de lignes de code, ce qui explique pourquoi chaque API HTTP de la planète finit par s'y rallier.

Les navigateurs analysent JSON nativement avec JSON.parse, chaque stdlib backend a un module JSON, et des variantes binaires comme MessagePack et CBOR existent quand vous dépassez la représentation textuelle. Pour les charges utiles requête/réponse, l'expédition de logs, l'état JS persisté et les bases de données documentaires, JSON est presque toujours le bon défaut.

YAML : le compromis idéal pour la configuration

YAML, à l'origine Yet Another Markup Language puis renommé récursivement YAML Ain't Markup Language, est un strict surensemble de JSON en version 1.2. Tout ce qui est légal en JSON est légal en YAML, mais YAML ajoute les commentaires, les chaînes multilignes, les ancres et alias pour la réutilisation, les balises de type explicites, et surtout une syntaxe basée sur l'indentation qui élague la majeure partie du bruit de ponctuation.

Cette lisibilité explique pourquoi YAML domine la configuration. Manifestes Kubernetes, charts Helm, playbooks Ansible, GitHub Actions, GitLab CI, Docker Compose, specs OpenAPI, projets dbt, et la plupart des CLI modernes lisent du YAML. Quand un humain va éditer un fichier dans un éditeur et le relire dans une pull request, YAML l'emporte.

CSV : la poignée de main universelle des tableurs

CSV, comma-separated values, précède le web et est décrit vaguement par RFC 4180. C'est d'une simplicité absolue : la première ligne est habituellement un en-tête, chaque ligne suivante est un enregistrement, et les champs sont séparés par un délimiteur (souvent une virgule, mais la tabulation, le point-virgule et la barre verticale sont aussi courants). Les chaînes contenant le délimiteur, un saut de ligne ou un guillemet double sont enveloppées de guillemets doubles, et les guillemets internes sont échappés en les doublant.

Le CSV est le format que tout tableur sur Terre, tout outil BI, tout chargeur en masse de base de données et tout analyste avec un notebook Python comprend sans cérémonie. C'est un format terrible pour les données imbriquées et un format merveilleux pour les tables plates. Quand le consommateur est un humain avec Excel ouvert, le CSV est presque toujours la bonne réponse.

Mêmes données, trois formats

Épinglons les différences avec un exemple concret. Imaginez une liste de trois utilisateurs, chacun avec un id, un nom, un e-mail, un rôle et une liste d'étiquettes. Voici la version JSON.

[
  {
    "id": 1,
    "name": "Ada Lovelace",
    "email": "ada@example.com",
    "role": "admin",
    "tags": ["founder", "math"]
  },
  {
    "id": 2,
    "name": "Linus Torvalds",
    "email": "linus@example.com",
    "role": "maintainer",
    "tags": ["kernel", "git"]
  },
  {
    "id": 3,
    "name": "Grace Hopper",
    "email": "grace@example.com",
    "role": "admin",
    "tags": ["compiler", "navy"]
  }
]

La même charge utile en YAML

Remarquez comme la ponctuation s'efface. La structure est entièrement portée par l'indentation, et la liste des étiquettes peut être écrite soit en ligne (style flow, identique à JSON), soit en bloc. Les commentaires sont légaux et fréquemment utiles.

# Seed users for the staging environment
- id: 1
  name: Ada Lovelace
  email: ada@example.com
  role: admin
  tags:
    - founder
    - math
- id: 2
  name: Linus Torvalds
  email: linus@example.com
  role: maintainer
  tags: [kernel, git]   # flow style is fine for short lists
- id: 3
  name: Grace Hopper
  email: grace@example.com
  role: admin
  tags:
    - compiler
    - navy

Et en CSV

Le CSV ne peut pas exprimer nativement le tableau imbriqué d'étiquettes, donc nous devons l'aplatir. Une convention courante est de joindre la liste avec un délimiteur secondaire comme une barre verticale ou un point-virgule et de documenter ce choix quelque part. La ligne d'en-tête remplace les noms de champs, et chaque enregistrement est sur sa propre ligne.

id,name,email,role,tags
1,Ada Lovelace,ada@example.com,admin,founder|math
2,Linus Torvalds,linus@example.com,maintainer,kernel|git
3,Grace Hopper,grace@example.com,admin,compiler|navy

Trois formats, trois tailles

La taille de fichier compte plus que les gens ne l'admettent. Pipelines de logs, bundles navigateur et factures de stockage s'en soucient tous. Pour l'exemple ci-dessus, les compteurs d'octets approximatifs sont : JSON environ 410 octets joliment imprimé et 290 minifié ; YAML environ 320 octets ; CSV environ 200 octets. Le CSV gagne haut la main sur les données plates parce qu'il amortit les noms de champs sur chaque ligne au lieu de les répéter.

Dès que vous commencez à imbriquer, l'image bascule. JSON et YAML restent à peu près constants par enregistrement tandis que le CSV doit soit aplatir avec des conventions que vous inventez, soit exploser en plusieurs feuilles. Pour un seul utilisateur profondément imbriqué avec vingt champs, JSON et YAML seront plus petits et plus clairs que tout CSV que vous pouvez construire.

Où chaque format gagne en pratique

Reconnaissance des motifs que les vraies équipes utilisent :

• JSON pour les API HTTP, les charges utiles WebSocket, le localStorage du navigateur, les lignes de log (en particulier JSON Lines), les bases de données documentaires comme MongoDB, et tout contrat inter-services.
• YAML pour Kubernetes, Helm, Argo, les workspaces Terraform Cloud, les pipelines GitHub ou GitLab CI, les specs OpenAPI et AsyncAPI, la configuration applicative que les humains éditent, et l'infrastructure-as-code où la lisibilité prime sur la vitesse de parsing.
• CSV pour les exports analytiques, les imports CRM, les tables de staging ETL, les jeux de données de machine learning, les rapports financiers, et tout ce qui est destiné à Excel ou Google Sheets.
• Ne prenez aucun des trois si vos données sont binaires, à très haut débit, ou fortement typées entre services. Protobuf, Avro ou Parquet sont généralement la bonne réponse là.

Pièges JSON qui mordent

Le minimalisme de JSON est une fonctionnalité, mais il crée quelques pièges. La spec interdit les commentaires, donc les fichiers de configuration écrits en JSON ne peuvent pas s'expliquer eux-mêmes. Les virgules de fin après le dernier élément de tableau ou d'objet sont illégales même si tout langage moderne les accepte. Les nombres sont des flottants 64 bits par défaut, donc tout entier supérieur à 2 puissance 53 perd silencieusement en précision, raison pour laquelle de nombreuses API sérialisent les gros ID sous forme de chaînes.

JSON n'a pas non plus de type date natif. Les chaînes ISO 8601 sont la convention de facto, mais vous et votre consommateur devez vous mettre d'accord. Et les clés en double dans le même objet sont techniquement autorisées par la grammaire mais produisent un comportement indéfini selon les parseurs, alors n'en dépendez pas.

Pièges YAML qui mordent plus fort

La flexibilité de YAML est sa faiblesse. L'indentation est significative, donc mélanger tabulations et espaces ou perdre deux caractères d'espace en début de ligne change silencieusement le sens de votre fichier. Le fameux problème de la Norvège fait encore surface dans les parseurs YAML 1.1 : le jeton non cité NO est analysé comme le booléen false, ce qui a saboté plus d'une liste de codes pays. YAML 1.2 corrige cela mais beaucoup d'outillage embarque encore la sémantique 1.1.

Les chaînes qui ressemblent à des nombres, des dates ou des booléens sont coercées sauf si vous les citez. Les ancres et alias (la syntaxe &foo et *foo) sont puissants mais invitent au déni de service de type « billion laughs » si vous acceptez du YAML non fiable. Analysez toujours le YAML fourni par l'utilisateur avec un loader sûr.

Pièges CSV qui mordent en silence

Le CSV est le format le plus susceptible de paraître correct tout en étant subtilement cassé. Il n'y a pas de standard pour le délimiteur ; les locales européennes exportent avec des points-virgules parce que la virgule est un séparateur décimal, et votre importateur doit le détecter. Les sauts de ligne à l'intérieur des champs cités sont légaux mais font trébucher les séparateurs de lignes naïfs. Excel reformatera joyeusement les numéros de téléphone et les longs ID en notation scientifique quand il ouvrira un CSV, mutilant vos données avant même qu'un humain ne les voie.

L'encodage est l'autre mine. Le CSV n'a pas de déclaration d'encodage, donc un fichier qui s'ouvre proprement sur macOS peut afficher du mojibake sur Windows à cause d'UTF-8 versus Windows-1252. Dans le doute, écrivez un BOM UTF-8, documentez le délimiteur, et citez tout champ chaîne.

Convertir en toute sécurité entre eux

La plupart des vrais systèmes vivent dans plus d'un de ces formats. Vous ingérez un CSV d'un fournisseur, le transformez en JSON pour une API, et émettez du YAML pour configurer le worker qui traite le résultat. Faire ces conversions à la main est d'où viennent les bogues, raison pour laquelle Multilities embarque des convertisseurs dédiés.

Si vous basculez entre JSON et YAML, le convertisseur /tools/yaml-json gère les deux directions et préserve les commentaires quand il le peut. Pour les données tabulaires, /tools/csv-json transforme les exports CSV en tableaux JSON que vous pouvez coller directement dans un fichier de fixtures ou une requête Postman, et vice versa quand vous devez tendre un tableur à la finance. Et quand vous voulez juste qu'un blob JSON se lise comme s'il avait été écrit par un humain, /tools/json-formatter trie les clés, corrige l'indentation et valide la structure en un seul passage.

Une liste de contrôle décisionnelle

Quand vous n'êtes pas sûr, parcourez cette liste de haut en bas et arrêtez-vous au premier oui.

• Le consommateur est-il un tableur ou un chargeur en masse SQL et les données sont-elles plates ? Utilisez CSV.
• Un humain va-t-il éditer ce fichier dans un éditeur de code et le relire dans une pull request ? Utilisez YAML.
• Le consommateur est-il un programme, en particulier à travers le réseau, et voulez-vous un minimum de cérémonie et un maximum d'outillage ? Utilisez JSON.
• Sérialisez-vous des millions d'enregistrements à haut débit avec un schéma fixe ? Sautez les trois et passez à Protobuf, Avro ou Parquet.

Pour conclure

Les trois formats ne sont pas tant des concurrents que des spécialistes. JSON est le format d'échange universel, YAML est le langage de configuration convivial pour les humains, et CSV est la poignée de main des tableurs qui refuse de mourir parce que rien d'autre n'est aussi universellement compris par les non-développeurs. Connaître le travail pour lequel chacun a été conçu, et connaître les pièges, c'est ce qui sépare les équipes qui livrent des pipelines de données propres des équipes qui combattent des bogues d'échappement chaque vendredi après-midi.

Gardez les outils de conversion en favoris, notez quel délimiteur et quel encodage utilisent vos CSV, citez vos chaînes YAML dans le doute, et ne faites jamais confiance à un ID 64 bits non signé pour survivre à un aller-retour à travers JavaScript. Faites cela et le format que vous choisissez disparaîtra majoritairement à l'arrière-plan, ce qui est exactement ce qu'un bon format de données est censé faire.