TOML vs YAML (et JSON) : la même config de trois façons | We.Inc
Comparez TOML, YAML et JSON sur les mêmes fichiers de configuration, côte à côte. Voyez où chaque format est imposé, de pyproject.toml et Cargo.toml à compose.yaml.
TOML est un format proche de INI conçu pour les fichiers de configuration : en-têtes [table] explicites, chaînes entre guillemets, vrais types de date et aucune indentation significative. YAML repose sur l'indentation, devine les types à partir des valeurs nues et ajoute les ancres et les documents multiples. Pour des réglages peu imbriqués, TOML est plus difficile à casser ; pour une imbrication profonde, YAML se lit mieux.
TOML, YAML et JSON en un coup d'œil
TOML 1.0
YAML 1.2
JSON
Imbrication
En-têtes [table] et [a.b]
Indentation
Accolades
Commentaires
Aucun
Chaînes
Toujours entre guillemets
Guillemets facultatifs
Toujours entre guillemets doubles
Dates et heures
Types intégrés
Absents du schéma core 1.2
Chaînes uniquement
Sensible à la casse
Oui
Oui
Oui
Type de média
application/toml
application/yaml
application/json
La plupart du temps, vous n'avez pas le choix : le packaging Python lit pyproject.toml, Rust lit Cargo.toml, et GitHub Actions comme Docker Compose lisent du YAML. Quand vous avez le choix, voir une même config dans les trois formats rend les compromis évidents. Choisissez un exemple ci-dessous et comparez.
Choisissez l'une des configs d'exemple : réglages d'app, manifeste de paquet ou liste de serveurs.
Lisez les mêmes données en TOML, YAML et JSON côte à côte.
Repérez où TOML a besoin d'en-têtes ([[servers]]) et où YAML exige une indentation soignée.
Copiez la version qu'attend votre outil.
Les longues listes d'enregistrements similaires sont le point où TOML devient verbeux : chaque entrée a besoin de son propre en-tête [[name]].
TOML interdit de définir deux fois la même clé ou la même table, ce qui attrape des erreurs de copier-coller que YAML peut laisser passer selon le parser.
Mettez les numéros de version entre guillemets en YAML. TOML n'a pas ce piège, car un texte nu n'y est jamais une chaîne valide.
Gardez un seul format par dépôt quand c'est possible. Mélanger les formats n'est acceptable que lorsque chaque outil impose le sien.
Questions fréquentes
TOML est-il meilleur que YAML ?
Aucun ne gagne partout. Les en-têtes explicites et les guillemets obligatoires de TOML rendent les petits et moyens fichiers de configuration difficiles à mal lire. YAML gère l'imbrication profonde et les longues listes avec moins de bruit, au prix d'une syntaxe sensible aux espaces et d'un typage implicite.
Pourquoi Python utilise-t-il pyproject.toml ?
Les guides de packaging Python définissent pyproject.toml avec trois tables : [build-system] pour le backend de build, [project] pour les métadonnées comme le nom, la version et les dépendances, et [tool] pour les réglages d'outils individuels comme les linters.
TOML peut-il représenter tout ce que YAML représente ?
Pas tout. TOML n'a ni ancres ni alias, ni documents multiples par fichier, ni null, puisque chaque clé doit recevoir une valeur. Pour de la configuration, cela compte rarement, mais des données YAML qui s'appuient sur ces fonctionnalités ne se convertiront pas à l'identique.
Quels formats acceptent Docker Compose et GitHub Actions ?
Les deux utilisent YAML. Les workflows GitHub Actions se trouvent dans .github/workflows avec une extension .yml ou .yaml, et Compose cherche compose.yaml par défaut, tout en acceptant encore docker-compose.yaml pour les projets plus anciens.
TOML prend-il en charge les chaînes multilignes ?
Oui. Trois guillemets doubles ouvrent une chaîne basique multiligne qui accepte les échappements, et trois guillemets simples ouvrent une chaîne littérale multiligne qui conserve son contenu exactement tel qu'il est écrit.
Où chaque format est imposé
Les projets Python se décrivent dans pyproject.toml et les crates Rust dans Cargo.toml : TOML est donc la norme dans ces écosystèmes. Hugo accepte aussi un front matter TOML entre des lignes +++.
Les pipelines CI, les configurations de conteneurs et les manifestes de déploiement s'appuient sur YAML : les workflows GitHub Actions et les fichiers Docker Compose sont tous deux en YAML, et le choix de l'extension relève surtout de la cohérence.
Ce que TOML sacrifie pour la sûreté
L'objectif de TOML, selon sa propre spécification, est de correspondre sans ambiguïté à une table de hachage. Donc pas de devinette : le texte exige des guillemets, les booléens sont uniquement true et false, et chaque table est nommée dans un en-tête.
Le prix, c'est la répétition dans les données imbriquées. À trois niveaux de profondeur, un fichier TOML répète le chemin de la table dans chaque en-tête, là où YAML se contente d'indenter.
Quels fichiers utilisent quel format
Fichiers de configuration courants et le format qu'ils imposent
Fichier
Format
Lu par
TOML
Les outils de build et de packaging Python
Cargo.toml
TOML
Cargo, le gestionnaire de paquets Rust
.github/workflows/*.yml
YAML
GitHub Actions
YAML
Docker Compose
JSON
npm et les autres gestionnaires de paquets Node
Front matter Markdown
YAML (TOML avec +++ dans Hugo)
Les générateurs de sites statiques
La syntaxe TOML à connaître
Clés pointées, tables inline et dates
Les clés pointées et les tables inline évitent des en-têtes supplémentaires pour les petits groupes, et les dates sont des valeurs typées, pas des chaînes.
Une config en TOML, YAML et JSON
Choisissez un exemple. Les trois versions contiennent exactement les mêmes données, pour comparer la façon dont chaque format les écrit.
Config d'exemple
TOML
YAML
JSON
Dans l'exemple de réglages d'app, TOML stocke opens comme une vraie heure locale, alors que les versions YAML et JSON la gardent sous forme de chaîne.