YAML vs JSON : différences, exemples et lequel choisir

YAML vs JSON, en bref : deux formats texte pour les mêmes données (objets, listes, chaînes, nombres, booléens et null). JSON est strict, utilise accolades et guillemets, et sert par défaut aux API web. YAML repose sur l'indentation, accepte commentaires, ancres et plusieurs documents par fichier ; il est prisé pour la configuration. YAML 1.2 est presque un sur-ensemble de JSON.

Essayez gratuitement : Convertisseur YAML en JSON Gratuit, sans création de compte.

JSON (JavaScript Object Notation, défini dans la RFC 8259) a été conçu pour l'échange de données entre programmes. Alors, qu'est-ce que YAML ? Son nom signifie « YAML Ain't Markup Language », et il a été conçu pour que des humains lisent et modifient des données à la main. Ce guide présente les mêmes données dans les deux formats, les compare et passe en revue les pièges de chacun. Pour voir à quoi ressemble un fichier dans l'autre format, collez-le dans le convertisseur YAML en JSON gratuit ou dans le convertisseur JSON vers YAML.

Les mêmes données en JSON et en YAML

Voici une petite configuration d'application en JSON :

{
  "name": "web-app",
  "version": "2.4.1",
  "replicas": 3,
  "debug": false,
  "database": {
    "host": "db.example.com",
    "port": 5432
  },
  "features": ["login", "search"],
  "maintainer": null
}

Et les mêmes données en YAML, avec en plus un commentaire, ce que JSON ne permet pas :

# Settings for the web app
name: web-app
version: 2.4.1
replicas: 3
debug: false
database:
  host: db.example.com
  port: 5432
features:
  - login
  - search
maintainer: null

Une fois analysés, les deux donnent exactement le même objet. JSON marque la structure avec {}, [], des virgules et des guillemets ; YAML la marque par l'indentation, des paires key: value et - pour les éléments de liste. En YAML, la plupart des chaînes n'ont besoin d'aucun guillemet, c'est pourquoi il se lit davantage comme un fichier de paramètres que comme du code.

YAML vs JSON : les principales différences

JSON YAML
Structure Accolades, crochets et virgules Indentation (espaces uniquement)
Commentaires Interdits # comment
Chaînes Toujours entre guillemets doubles Généralement sans guillemets ; 'single' ou "double" si nécessaire
Types de données Objet, tableau, chaîne, nombre, booléen, null Les mêmes, plus des tags facultatifs, des horodatages dans certains schémas et des types personnalisés
Réutilisation Aucune Ancres &, alias * et clés de fusion <<
Plusieurs documents par fichier Non (une seule valeur par fichier) Oui, séparés par ---
Texte multiligne Uniquement avec des échappements \n Scalaires de bloc | et >
Analyse Grammaire courte et stricte ; intégrée aux navigateurs et à de nombreuses bibliothèques standard Grammaire plus vaste ; généralement une bibliothèque tierce
Usages typiques API REST, package.json, journaux, données échangées entre programmes Manifestes Kubernetes, workflows GitHub Actions, Docker Compose, Ansible

Certains formats acceptent les deux : les descriptions OpenAPI peuvent être écrites dans l'un ou l'autre, et kubectl apply lit les manifestes JSON comme les manifestes YAML. En règle générale, JSON l'emporte quand ce sont des programmes qui écrivent et lisent les données ; YAML l'emporte quand des humains les maintiennent à la main et ont besoin de commentaires.

YAML est-il un sur-ensemble de JSON ?

Presque. La spécification YAML 1.2 (2009) visait à faire de YAML un sur-ensemble strict de JSON, et en pratique un parseur YAML 1.2 lit presque n'importe quel document JSON et renvoie les mêmes données. Deux réserves :

L'inverse n'est pas vrai : la plupart des fichiers YAML ne sont pas du JSON valide.

Les pièges de YAML à connaître

Le problème norvégien (Norway problem) : NO devient false

En YAML 1.1, les mots sans guillemets yes, no, on et off (en minuscules, avec une majuscule initiale ou en majuscules) sont des booléens, au même titre que true et false. Ainsi, cette liste de codes pays :

countries:
  - GB
  - NO
  - SE

est chargée comme ["GB", false, "SE"] par un parseur YAML 1.1 tel que PyYAML. La même règle transforme la clé on: d'un workflow GitHub Actions en booléen True quand on charge le fichier avec PyYAML. Le schéma core de YAML 1.2 a corrigé cela : seuls true et false (également écrits True ou TRUE) sont des booléens, donc un parseur 1.2 conserve NO comme chaîne. Comme on contrôle rarement quel parseur lira le fichier, le bon réflexe est de mettre ces valeurs entre guillemets : - "NO".

Des nombres qui ne devraient pas en être

Tabulations et espaces significatifs

La spécification YAML interdit les tabulations pour l'indentation : une tabulation en début de ligne est donc une erreur de syntaxe, pas une question de style. L'indentation a aussi un sens : décaler une clé de deux espaces vers la gauche la rattache à un autre objet parent, et le fichier peut rester parfaitement valide tout en signifiant autre chose.

Chaînes multilignes : | et >

Un bloc littéral (|) conserve les sauts de ligne ; un bloc replié (>) joint les lignes avec des espaces :

literal: |
  Line one
  Line two
folded: >
  This long sentence is
  folded into one line.

literal devient "Line one\nLine two\n" et folded devient "This long sentence is folded into one line.\n". Les deux conservent un saut de ligne final ; écrivez |- ou >- pour le supprimer.

Ancres, alias et clés de fusion

YAML permet de définir un bloc une seule fois et de le réutiliser :

defaults: &defaults
  adapter: postgres
  port: 5432
production:
  <<: *defaults
  host: db.example.com

&defaults nomme le bloc, *defaults y fait référence et << fusionne ses clés, si bien que production se retrouve avec adapter, port et host. JSON n'a pas d'équivalent : la conversion en JSON recopie les valeurs à chaque endroit où elles sont utilisées. Les clés de fusion viennent de YAML 1.1 et ne font pas partie du schéma core de la 1.2, mais la plupart des parseurs courants les prennent encore en charge.

Les pièges de JSON à connaître

JSON est strict, et trois règles causent la plupart des erreurs :

Ce fichier échoue donc avec JSON.parse :

{
  // port for local development
  'port': 8080,
  "tags": ["api", "v2",],
}

Pour les fichiers écrits à la main, il existe des variantes plus souples : JSONC (« JSON with comments », du JSON avec commentaires) est utilisé par les paramètres de VS Code et par tsconfig.json, et JSON5 autorise en plus les guillemets simples, les clés sans guillemets et les virgules finales. Aucun des deux n'est accepté par un parseur JSON standard. Le formateur JSON accepte une entrée JSON5, la signale par « JSON5 valide — converti en JSON strict » et vous rend du JSON standard.

.yaml vs .yml

YAML vs YML n'est pas une question de format : les deux extensions désignent le même format, et les parseurs ne se soucient pas de celle que vous utilisez. La RFC 9512, qui a enregistré le type de média application/yaml en 2024, désigne .yaml comme l'extension préférée et note que .yml reste utilisée. La FAQ du projet YAML recommandait aussi .yaml, et Docker Compose cherche compose.yaml avant compose.yml. GitHub Actions accepte les deux dans .github/workflows. Choisissez-en une par projet et ne gardez pas config.yaml et config.yml côte à côte.

Sécurité : charger du YAML non fiable sans risque

Les chargeurs YAML complets peuvent construire des objets propres au langage à partir de tags. En Python, yaml.load(data, Loader=yaml.UnsafeLoader) peut créer des objets Python arbitraires et, avec un fichier forgé, exécuter du code. Utilisez toujours yaml.safe_load() pour les fichiers que vous n'avez pas écrits : il ne construit que des dictionnaires, listes, chaînes, nombres, booléens et null ordinaires. Depuis PyYAML 6.0, yaml.load() refuse de s'exécuter sans Loader explicite. Méfiez-vous aussi des alias profondément imbriqués (fichiers « billion laughs ») qui se déploient en structures gigantesques. JSON n'a ni tags ni alias, donc JSON.parse et json.loads de Python ne renvoient jamais que des données simples.

Convertir entre YAML et JSON

Les deux convertisseurs fonctionnent entièrement dans votre navigateur et utilisent la bibliothèque open source yaml pour JavaScript.

Le convertisseur YAML en JSON analyse YAML 1.2, développe les ancres et les alias, applique les clés de fusion << et transforme un fichier contenant plusieurs documents --- en tableau JSON. Vous pouvez choisir une indentation de 2, 3 (par défaut) ou 4 espaces, des tabulations ou une sortie minifiée, trier les clés par ordre alphabétique et télécharger le résultat sous le nom converted.json. Les erreurs de syntaxe, comme une tabulation utilisée pour l'indentation, sont affichées avec leur ligne et leur colonne. Les commentaires sont perdus, car JSON ne peut pas les stocker.

Le convertisseur JSON vers YAML lit le JSON standard et le JSON5 : les commentaires et virgules finales en entrée sont donc acceptés, mais pas repris. Il produit du YAML indenté de deux espaces et n'a aucune option. La sortie suit YAML 1.2 : des chaînes comme "0755" et "true" sont mises entre guillemets, mais NO, yes ou on restent sans guillemets, car ce sont des chaînes ordinaires en 1.2. Si un outil YAML 1.1 comme PyYAML doit lire le fichier, ajoutez vous-même les guillemets à ces valeurs.

En ligne de commande, yq de Mike Farah convertit dans les deux sens, et jq valide et met en forme le JSON :

yq -o json config.yaml
yq -P -oy config.json
jq . config.json

Quand utiliser YAML et quand utiliser JSON

Le choix JSON vs YAML dépend généralement de qui écrit le fichier :

Si vous choisissez YAML, restez sobre : indentation de deux espaces, guillemets autour de tout ce qui pourrait être lu comme un booléen ou un nombre, et un linter comme yamllint dans la CI.

Questions fréquentes

YAML est-il meilleur que JSON ?

Aucun n'est meilleur dans l'absolu. JSON est plus simple et plus strict, ce qui en fait le choix le plus sûr pour les données échangées entre programmes. YAML est plus facile à lire et à modifier pour les humains et accepte les commentaires, c'est pourquoi tant de fichiers de configuration l'utilisent.

Peut-on utiliser du JSON dans un fichier YAML ?

Oui. Le style flow de YAML utilise les mêmes crochets et accolades que JSON, donc ports: [80, 443] ou db: {"host": "localhost"} fonctionne dans un fichier YAML, et un parseur YAML 1.2 accepte presque n'importe quel document JSON complet. Les clés en double sont la principale exception.

JSON peut-il contenir des commentaires ?

Pas en JSON standard : la RFC 8259 ne prévoit aucune syntaxe de commentaire, et JSON.parse échoue sur // ou /* */. Certains outils acceptent JSONC ou JSON5, qui autorisent les commentaires, mais vous devez les supprimer avant de passer le fichier à un parseur strict.

Quelle est la différence entre YAML et YML ?

Aucune sur le fond : .yaml et .yml sont deux extensions de fichier pour le même format. La RFC 9512 désigne .yaml comme l'extension préférée, mais les parseurs YAML ne tiennent pas compte de l'extension.

Pourquoi YAML transforme-t-il NO ou on en false ou true ?

Parce que YAML 1.1 traite yes, no, on et off comme des booléens. YAML 1.2 ne traite que true et false comme des booléens, mais de nombreux parseurs, dont PyYAML, appliquent encore les règles de la 1.1. Mettez ces valeurs entre guillemets, par exemple country: "NO", et tous les parseurs les liront comme des chaînes.

Essayez gratuitement : Convertisseur YAML en JSON Gratuit, sans création de compte.