YAML vs JSON : différences, pièges et .yaml vs .yml | We.Inc
YAML vs JSON côte à côte : syntaxe, commentaires, types, texte multiligne et le piège yes/no. Testez comment une valeur brute est lue, et tranchez une fois pour toutes entre .yaml et .yml.
JSON est un format de données strict pensé pour les programmes : accolades, crochets, chaînes entre guillemets doubles et aucun commentaire. YAML exprime les mêmes données avec l'indentation, autorise les commentaires et le texte multiligne, et sa version 1.2 a été conçue comme un sur-ensemble de JSON. Choisissez JSON pour les API et les sorties machine, YAML pour les fichiers modifiés à la main.
YAML et JSON comparés fonctionnalité par fonctionnalité
Fonctionnalité
JSON
YAML 1.2
Structure
Accolades et crochets
Indentation (espaces uniquement), ou style flow façon JSON
Commentaires
Interdits
Chaînes
Toujours entre guillemets doubles
Sans guillemets, entre guillemets simples ou doubles
Texte multiligne
\n échappé dans une seule chaîne
Block scalars avec | ou >
Réutiliser une valeur
Non
Ancres (&) et alias (*)
Plusieurs documents dans un fichier
Non
Oui, séparés par ---
Type de média
application/json
application/yaml
Les deux formats décrivent les mêmes choses : objets, listes, chaînes, nombres, booléens et null. Les vraies différences tiennent à qui lit le fichier et à la tolérance du parseur. Essayez le vérificateur de valeurs ci-dessous pour voir comment une valeur sans guillemets est typée, puis lisez les exemples côte à côte et les pièges qui guettent ceux qui passent de l'un à l'autre.
Saisissez une valeur brute, comme yes, 0x1F, 1e3 ou ~, dans le vérificateur.
Voyez comment un parseur YAML 1.2 la type, ce qu'un ancien parseur YAML 1.1 peut faire différemment, et si JSON l'accepte telle quelle.
Comparez le même enregistrement écrit dans les deux formats dans les exemples plus bas.
Mettez entre guillemets toute valeur dont le type vous a surpris, puis gardez ce réflexe dans vos fichiers de configuration.
Indentez le YAML avec des espaces. La spécification interdit les tabulations dans l'indentation, et la plupart des erreurs d'analyse dans les fichiers modifiés à la main viennent d'une tabulation égarée.
Mettez entre guillemets les codes pays, les numéros de version et tout ce qui ressemble à yes, no, on ou off. Certains parseurs suivent encore les règles de YAML 1.1 et en font des booléens.
Si un outil accepte les deux formats, générez du JSON depuis le code et gardez le YAML pour les fichiers maintenus par des humains.
Validez les deux : passez le JSON dans un formateur, et chargez le YAML avec la même bibliothèque que votre application, car les parseurs divergent sur les cas limites.
Questions fréquentes
Tout fichier JSON est-il du YAML valide ?
YAML 1.2 a été écrit pour être un sur-ensemble strict de JSON : en pratique, un document JSON se charge donc dans un parseur YAML 1.2. Il existe des cas limites, comme les clés en double, que les parseurs JSON tolèrent souvent mais que YAML interdit.
Faut-il utiliser .yaml ou .yml ?
Utilisez .yaml. La RFC 9512, qui enregistre le type de média application/yaml, désigne .yaml comme l'extension recommandée et note que .yml reste utilisée. Les deux fonctionnent dans des outils comme GitHub Actions : le choix est une question de cohérence au sein d'un même projet.
Pourquoi ma valeur YAML est-elle devenue true ou false ?
YAML 1.1 traitait des mots comme yes, no, on, off, y et n comme des booléens. Le core schema de YAML 1.2 n'accepte que true et false sous trois casses, mais les anciens parseurs restent courants. Mettre la valeur entre guillemets lève le doute.
JSON peut-il contenir des commentaires ?
Non. La RFC 8259 liste les éléments que JSON peut contenir et les commentaires n'en font pas partie. Certains outils acceptent un JSON assoupli avec commentaires, mais un parseur strict rejettera le fichier.
Lequel est le plus rapide à analyser ?
La grammaire de JSON est bien plus petite et les navigateurs intègrent un parseur natif : c'est donc généralement le choix le plus rapide et le plus sûr pour les données envoyées sur le réseau. Les parseurs YAML ont bien plus de règles à appliquer, de l'indentation au typage implicite.
Quand JSON est le meilleur choix
Les API, le stockage navigateur, les logs et tout ce qu'un programme écrit pour qu'un autre le lise. La grammaire est minuscule, chaque langage dispose d'un parseur strict, et il n'y a qu'une façon d'écrire chaque valeur : les diffs restent donc prévisibles.
JSON n'a pas non plus de typage implicite. Une chaîne est une chaîne parce qu'elle a des guillemets, ce qui élimine toute une catégorie de surprises.
Quand YAML est le meilleur choix
La configuration que des personnes lisent et modifient : workflows de CI, configurations de conteneurs, front matter de sites et manifestes de déploiement. Les commentaires permettent d'expliquer pourquoi un réglage existe, et les block scalars gardent lisibles les scripts shell et les longs messages.
La contrepartie : les espaces ont un sens et les valeurs sans guillemets sont devinées. Gardez des fichiers courts, mettez entre guillemets tout ce qui est ambigu et lancez un linter en CI.
Un même enregistrement, écrit dans les deux formats
Les mêmes réglages de site dans les deux formats. YAML supprime les guillemets et les accolades et ajoute un commentaire ; JSON écrit en toutes lettres chaque chaîne et chaque niveau d'imbrication.
Indentation de deux espaces, un commentaire, une liste et un numéro de version entre guillemets pour qu'il reste du texte.
Aucun commentaire possible, et chaque clé et chaîne porte des guillemets doubles.
Les valeurs qui changent de type quand on oublie les guillemets
Comment une valeur YAML sans guillemets est typée, et la version sûre
Vous avez écrit
Lecture par le core schema YAML 1.2
Plus sûr
version: 2.10
float 2.1 (le zéro final est perdu)
version: "2.10"
country: NO
chaîne en 1.2, booléen false en 1.1
country: "NO"
port: 0x1F90
entier 8080
port: 8080
mode: 0o755
entier 493
mode: "0o755"
value: ~
value: null
ratio: .inf
float infini (aucune forme JSON)
ratio: "inf"
Comment cette valeur brute sera-t-elle lue ?
Saisissez une valeur telle qu'elle apparaîtrait après les deux-points dans un fichier YAML, sans guillemets. Le vérificateur applique les règles du core schema YAML 1.2, la liste des booléens de YAML 1.1 et la grammaire JSON.
Valeur sans guillemets
Core schema YAML 1.2
Parseurs YAML 1.1
JSON, écrit tel quel
Même valeur en JSON
booléen {v} (YAML 1.1 lit ce mot comme un booléen)
Pas de piège de booléen façon yes/no pour cette valeur