Qu'est-ce que TOML ? Le langage de configuration qui a surpassé YAML
TOML : de quoi s'agit-il vraiment ?
TOML est l'acronyme de Tom's Obvious, Minimal Language. Son créateur, Tom Preston-Werner, cofondateur de GitHub, en avait assez des formats de configuration existants en 2013. Le langage a mûri pendant près de huit ans avant que la première version stable, TOML v1.0.0, ne soit lancée en janvier 2021. Cette longue période de raffinement te montre à quel point sa conception a été prise au sérieux. Au fond, TOML est un format de fichier de configuration. Ce n'est ni un format de sérialisation de données générique comme JSON, ni un langage de balisage. L'objectif principal est qu'il soit trivial à lire et à écrire pour un humain, tout en se mappant de manière non ambiguë à une table de hachage – ou ce que tu pourrais appeler un dictionnaire, une carte ou un objet dans ton langage de prédilection. Un fichier TOML minimal est d'une simplicité enfantine : ``` title = "My Application" version = "2.4.1" debug = false [database] host = "localhost" port = 5432 max_connections = 100 ``` Chaque valeur a un type explicite. `"localhost"` est une chaîne de caractères. `5432` est un entier. `false` est un booléen — pas la chaîne de caractères `"false"`, pas `0`, et pas `null`. Cette rigueur est tout l'intérêt, et c'est une raison principale pour laquelle les développeurs choisissent TOML. Tu ne perdras jamais de temps à te demander si ton numéro de port sera analysé comme une chaîne ou un entier à cause d'une bizarrerie dans une bibliothèque YAML spécifique.
Pourquoi YAML est devenu un problème à résoudre
YAML est souvent loué pour sa convivialité. Pour les petits fichiers, c'est vrai. Mais sa convivialité disparaît rapidement à mesure que ta configuration s'étoffe, et ses choix de conception commencent à poser problème. L'exemple le plus tristement célèbre est le Problème de la Norvège. Dans YAML 1.1 — encore la valeur par défaut pour de nombreux analyseurs — le code pays à deux lettres `NO` est interprété comme la valeur booléenne `false`. Une configuration comme `country: NO` corromprait silencieusement tes données. Cela s'applique à `yes`, `no`, `on`, `off`, `true`, et `false` dans diverses capitalisations. YAML 1.2 a corrigé cela, mais tu ne peux pas toujours contrôler la version de l'analyseur que tes outils utilisent. Ensuite, il y a l'espace blanc significatif. YAML utilise l'indentation pour définir la structure, donc un seul espace mal placé peut silencieusement modifier le sens entier de ton fichier ou simplement le casser complètement. Quiconque a passé une heure à déboguer un pipeline CI/CD pour découvrir une incohérence entre deux ou quatre espaces connaît intimement cette douleur. YAML offre également trop de façons d'écrire la même chose. Les scalaires peuvent être simples, entre guillemets simples, entre guillemets doubles ou de style bloc. Les séquences peuvent être de style flux ou bloc. Cette flexibilité semble agréable, mais elle signifie que deux développeurs écriront la même configuration logique de manières complètement différentes, rendant les comparaisons (diffs) plus difficiles à lire et les revues de code moins efficaces. Cela ne rend pas YAML inutile pour autant. C'est la norme pour les manifestes Kubernetes et les workflows GitHub Actions, et ce n'est pas sans raison. Mais pour la configuration d'applications, où la justesse et la prévisibilité importent plus que tout, ces bizarreries sont un sérieux inconvénient.
Comment TOML résout le problème de lisibilité
La philosophie de TOML est simple : il ne devrait y avoir qu'une seule façon évidente d'écrire quelque chose. Cela semble restrictif, mais le résultat, ce sont des fichiers de configuration qui ont la même apparence et la même sensation, peu importe qui les a écrits ou à quel projet ils appartiennent. Il offre six types scalaires : chaîne de caractères, entier, flottant, booléen, date-heure avec décalage et date locale. Le support de première classe de TOML pour les dates et heures au format RFC 3339 est une fonctionnalité vraiment géniale. Tu peux écrire `created_at = 2024-03-15T09:30:00Z` et avoir confiance que cela deviendra un objet datetime approprié, et non une chaîne que tu devrais analyser toi-même. Bien que YAML puisse représenter des dates, le comportement est incohérent d'un analyseur à l'autre. La structure est définie avec des tables (sections) et des tableaux de tables. Une table reçoit un en-tête entre crochets : `[server]`. Un tableau de tables utilise des doubles crochets : `[[products]]`. La syntaxe est non ambiguë et facile à repérer. Voici un exemple concret tiré d'un fichier Rust `Cargo.toml`, montrant comment les dépendances sont définies : ``` [dependencies] serde = { version = "1.0", features = ["derive"] } tokio = { version = "1", features = ["full"] } reqwest = "0.12" ``` La syntaxe de table en ligne — la partie entre accolades — est excellente pour des définitions simples et compactes. Pour des données imbriquées plus complexes, tu utilises des en-têtes de table complètes. Le langage te donne des règles claires sur le moment d'utiliser chaque style. Même les commentaires sont conçus pour être familiers. Ils utilisent le caractère `#`, tout comme Python et les scripts shell. La plupart des développeurs connaissent déjà la syntaxe sans avoir lu une seule ligne de la spécification.
Où TOML a gagné : les chiffres réels de son adoption
L'écosystème Rust est la plus grande réussite de TOML. Cargo, le gestionnaire de paquets de Rust, impose TOML pour ses manifestes. Avec plus de 150 000 paquets sur crates.io début 2025, chacun d'entre eux possède un fichier `Cargo.toml`. C'est un test de stress massif et réel que peu de formats ont réussi. L'adoption par Python via les PEP 518 (2016) et PEP 621 (2021) a fait de `pyproject.toml` le seul véritable endroit pour les métadonnées de projet et la configuration de construction. Des outils comme Poetry, Hatch, Flit et PDM l'utilisent tous. Tes paramètres de linter vont dans `[tool.ruff]`, tes paramètres de test dans `[tool.pytest.ini_options]`. Tu obtiens un seul fichier et un seul format pour les gouverner tous. Hugo, le générateur de sites statiques populaire, a fait de TOML son format de configuration par défaut, s'éloignant de YAML et JSON. L'équipe a spécifiquement cité l'explicité de TOML et l'absence de coercitions de type surprenantes comme motivation. Quand un langage ajoute un analyseur à sa bibliothèque standard, tu sais que le format a fait son entrée. Python a fait exactement cela en ajoutant `tomllib` dans la version 3.11 (publiée en octobre 2022), te permettant d'analyser les fichiers TOML sur n'importe quelle installation Python moderne sans aucune dépendance externe. Et ce n'est pas seulement une affaire de Python et Rust. Go, .NET et JavaScript ont tous des bibliothèques TOML matures et bien entretenues. Le paquet `@iarna/toml` sur npm, par exemple, compte des millions de téléchargements hebdomadaires. TOML est officiellement entré dans le courant dominant.
Les vraies limites de TOML
Aucun outil n'est parfait, et TOML ne fait pas exception. Il est important d'être honnête sur ses limites afin que tu saches quand te tourner vers autre chose. Les données profondément imbriquées sont le talon d'Achille de TOML. Si tu as besoin de plus de deux ou trois niveaux d'imbrication, la syntaxe devient pénible. Tu te retrouveras à écrire de longues clés pointillées comme `[servers.production.database.replica]`. C'est valide, mais ce n'est pas lisible. JSON et même YAML sont tout simplement meilleurs à cet égard car ils ont été conçus pour la représentation générale de données. Les grands tableaux d'objets complexes sont un autre point faible. La syntaxe `[[products]]` pour un tableau de tables signifie que tu dois répéter cet en-tête pour chaque élément. Une liste de 50 produits se traduit par 50 en-têtes `[[products]]` distincts. À ce stade, tu n'es plus en train d'écrire un fichier de configuration ; tu utilises le mauvais outil. Tu devrais utiliser JSON ou une base de données. TOML ne prend pas en charge les ancres et les alias, une fonctionnalité que YAML offre avec `&anchor` et `*alias`. Cela signifie que tu ne peux pas définir un bloc de paramètres une seule fois et le réutiliser dans tout ton fichier. Si tu as besoin de répéter une configuration, tu as deux choix : la dupliquer directement, ou intégrer une logique de fusion dans le code de ton application. Il n'y a pas de moyen intégré de le garder DRY (Don't Repeat Yourself). Enfin, tu ne peux pas diffuser un fichier TOML en streaming. Contrairement à JSON Lines, un document TOML doit être lu et analysé dans son intégralité avant que tu puisses accéder à ses valeurs. Cela peut avoir de l'importance pour des fichiers de configuration énormes, bien qu'un fichier de configuration aussi grand soit souvent le symptôme d'un problème de conception plus profond. Ces limitations ne font pas de TOML un mauvais choix pour son objectif : la configuration d'applications de complexité modérée. Elles définissent simplement ses limites.
Conversion entre TOML et d'autres formats
Si tu migres un projet de YAML ou si tu as simplement besoin de convertir des données de configuration entre formats pour un outil, tu as plusieurs options. Pour convertir de manière programmatique en Python, tu peux combiner les bibliothèques `tomllib` (lecture) et `tomli-w` (écriture) avec un analyseur YAML comme `PyYAML`. Lire un fichier YAML dans un dictionnaire Python avec `yaml.safe_load()` puis l'écrire avec `tomli_w.dumps()` fonctionne, mais c'est mieux pour les fichiers plats ou modérément imbriqués. Les structures profondément imbriquées, les ancres YAML ou les fichiers multi-documents nécessiteront un nettoyage manuel. Pour la conversion de JSON à TOML, le mappage est beaucoup plus propre car les deux formats ont des types explicites. Un entier JSON devient un entier TOML. Un booléen JSON devient un booléen TOML. Le principal changement structurel est la transformation des tableaux d'objets JSON en tableaux de tables TOML (`[[table]]`), ce qu'un bon convertisseur peut gérer. Des outils en ligne comme CocoConvert peuvent gérer la conversion pour toi. Télécharge un fichier JSON ou YAML, choisis TOML comme format de sortie, et le convertisseur fait le travail. C'est une excellente option pour les fichiers de configuration simples. Pour les fichiers avec des fonctionnalités spécifiques à YAML comme les ancres ou les structures profondément imbriquées, tu devras quand même vérifier le résultat. CocoConvert signalera les avertissements de conversion lorsqu'il trouvera quelque chose qui ne se mappe pas proprement à TOML, mais il ne peut pas refactoriser ta structure de données pour toi — c'est une décision que tu dois prendre. Pour les migrations en masse, comme la conversion d'un dépôt entier de 40 fichiers YAML, les télécharger un par un n'est pas une option viable. L'API CocoConvert est conçue pour cela, te permettant de regrouper les requêtes par lots et d'automatiser l'ensemble du processus.
Devrais-tu migrer ton projet vers TOML ?
Alors, devrais-tu changer ? La réponse dépend de ton projet et de ce que sa chaîne d'outils attend. Pour un nouveau projet Python en 2025, la réponse est un oui catégorique. Utilise `pyproject.toml`. L'écosystème s'est standardisé sur ce format, et lutter contre cela ne fait que créer des frictions inutiles. Ne sois pas la personne qui crée un `ruff.toml` séparé alors que la norme est d'utiliser la section `[tool.ruff]` dans le fichier de configuration principal du projet. Si tu écris un projet Rust, ce n'est même pas une question. Cargo utilise TOML, et c'est une fonctionnalité, pas un bug. La cohérence du format est une grande partie de la raison pour laquelle les outils de Rust semblent si cohérents. Pour un projet existant avec une configuration YAML fonctionnelle, je dirais de ne migrer que si ce YAML est une source de problèmes. Si ton `config.yaml` est stable et que l'équipe le comprend, le coût du changement — mise à jour de la documentation, des scripts et des habitudes des gens — ne vaut probablement pas la 'pureté' d'utiliser TOML. Dans le monde de Kubernetes et du CI/CD (GitHub Actions, GitLab CI, etc.), YAML est roi. Tu n'as pas le choix, et TOML n'essaie pas de le détrôner dans cette arène. Le véritable test décisif est le suivant : écris-tu des commentaires dans ton fichier YAML pour expliquer quel type de données une valeur *devrait* être ? Es-tu en train de chasser des bugs causés par un nombre lu comme une chaîne de caractères ? C'est ton signal. Tu as dépassé l'ambiguïté de YAML. TOML a été conçu pour résoudre précisément cette catégorie de problèmes en rendant les types explicites dès le départ.