Les mêmes données dans les deux formats
Voici une petite configuration en JSON : {"name": "shop", "port": 8080, "debug": false, "hosts": ["a.example.com", "b.example.com"]}. En YAML, les mêmes données s'écrivent avec de l'indentation au lieu d'accolades : name: shop sur une ligne, port: 8080 sur la suivante, debug: false, puis hosts: suivi de deux lignes indentées qui commencent par un tiret.
Les deux se chargent exactement dans le même objet, quel que soit le langage de programmation. La différence tient à la façon de les écrire et à ce que chaque format permet en plus.
| JSON | YAML | |
|---|---|---|
| Structure | Accolades et crochets | Indentation, ou accolades si vous préférez |
| Texte | Toujours entre guillemets doubles | Guillemets le plus souvent facultatifs |
| Commentaires | Interdits | Lignes qui commencent par # |
| Texte sur plusieurs lignes | Seulement avec \n dans une chaîne | Blocs avec | ou > |
| Réutiliser des parties | Impossible | Ancres (&nom) et alias (*nom) |
| Plusieurs documents dans un fichier | Non | Oui, séparés par une ligne de trois tirets |
| Usage typique | API, échange de données, navigateurs | Configuration : Docker Compose, Kubernetes, CI |
Essayez ici : YAML en JSON
Ouvrir la page complète de l'outilPourquoi le YAML est agréable à écrire
Le YAML demande moins de caractères. Pas d'accolades fermantes à compter, pas de virgules à oublier entre les éléments et pas de guillemets autour de la plupart des textes. Les commentaires permettent d'expliquer pourquoi un réglage existe, c'est pourquoi les outils que l'on modifie tous les jours, comme Docker Compose, Kubernetes, GitHub Actions et Ansible, l'ont choisi.
Les ancres évitent les répétitions : vous définissez un bloc une fois avec &defaults et vous le réutilisez avec *defaults, ou vous le fusionnez dans un autre bloc avec <<: *defaults en remplaçant certaines clés. Le texte en bloc garde ses retours à la ligne, ce qui rend les scripts et les longs messages lisibles dans le fichier.
Les pièges du YAML qui modifient vos données
La liberté d'omettre les guillemets a un prix : le YAML devine le type de chaque valeur sans guillemets, et sa supposition n'est pas toujours celle que vous aviez en tête. La plupart de ces problèmes disparaissent quand le texte est entre guillemets.
- Le problème de la Norvège : en YAML 1.1, que beaucoup d'outils utilisent encore, NO, no, yes, on et off sont des booléens. Une liste de codes pays où NO désigne la Norvège se transforme en false.
- Les numéros de version : 1.10 devient le nombre 1.1, et 3.0 peut devenir 3. Écrivez "1.10" pour le garder en texte.
- Les zéros initiaux : les codes postaux et références produit comme 0123 peuvent devenir des nombres, et YAML 1.1 les lit en octal, donc 0123 devient 83.
- Les heures : en YAML 1.1, 12:30 est un nombre en base 60, soit 750.
- Les deux-points et les dièses : une valeur qui contient ": " ou " #" se termine trop tôt ou commence un commentaire. Mettez ce genre de texte entre guillemets.
- Les tabulations : le YAML n'accepte pas les tabulations pour indenter, et une clé indentée d'un espace de trop atterrit dans le mauvais bloc sans aucune erreur dans certains éditeurs.
Pourquoi le JSON convient mieux aux programmes
Le JSON n'a qu'une façon d'écrire chaque chose et ne devine rien : le texte est toujours entre guillemets, donc "NO" reste du texte et 1.10 est clairement un nombre. Les analyseurs sont petits, rapides et disponibles dans tous les langages, et les navigateurs lisent le JSON nativement. Le JSON est donc le choix le plus sûr dès que des données sont produites et lues par des logiciels : réponses d'API, journaux, caches et fichiers de données.
L'absence de commentaires est le reproche le plus fréquent. Certains outils acceptent du JSON avec commentaires (souvent appelé JSONC), mais les analyseurs standard le refusent, ce n'est donc pas un bon format pour des fichiers que d'autres programmes doivent lire.
Convertir entre YAML et JSON sans risque
YAML 1.2 a été conçu comme un sur-ensemble de JSON : presque tout document JSON est donc aussi du YAML valide. Dans l'autre sens, il faut un vrai analyseur, car les fonctions du YAML doivent être résolues : les ancres et les clés de fusion sont développées, le texte en bloc devient une chaîne avec \n, et plusieurs documents deviennent une liste. Les commentaires ne peuvent pas suivre, puisque le JSON n'a pas de place pour eux.
Quand vous convertissez du JSON en YAML, chaque valeur qu'un lecteur YAML pourrait mal interpréter doit être mise entre guillemets. Le convertisseur de cette page vérifie chaque texte selon les règles de YAML 1.1 et de YAML 1.2 et ne le met entre guillemets que si c'est nécessaire : yes, NO, 0123 et 1.10 reviennent donc intacts. Reconvertir le résultat avec Inverser est un moyen rapide de prouver que rien n'a changé.
Lequel choisir ?
- Utilisez le YAML pour la configuration que des personnes écrivent et relisent à la main, surtout quand les commentaires sont utiles.
- Utilisez le JSON pour les données que des programmes échangent, stockent ou envoient sur le réseau.
- Utilisez le JSON quand le fichier est généré par du code, même si quelqu'un le lit ensuite.
- Si un outil accepte les deux, comme c'est souvent le cas, gardez le format que votre équipe utilise déjà : la cohérence compte plus que les petites différences.
- Si vous restez sur le YAML, mettez entre guillemets les textes qui ressemblent à des nombres, des dates ou à yes/no, et vérifiez vos fichiers avec un analyseur avant de les déployer.