Choisir un format de configuration : JSON, YAML ou TOML

Ce que c'est

JSON selon la RFC 8259 connaît les objets, les tableaux, les chaînes de caractères, les nombres, true, false et null — et pas de commentaires. La RFC indique que les noms au sein d'un objet devraient être uniques (SHOULD) et que le comportement des logiciels récepteurs face à des noms dupliqués est imprévisible : certains ne rapportent que la dernière paire, d'autres une erreur. YAML 1.2, selon sa spécification, a été conçu avec pour objectif principal d'être un sur-ensemble strict de JSON, et a supprimé nombre des recommandations problématiques relatives au typage implicite ; dans le schéma de base (Core Schema), les scalaires non cités continuent d'être résolus selon des motifs, de sorte que true, True et TRUE sont des valeurs booléennes, tandis que les chargeurs suivant l'ancien modèle 1.1 traitent aussi yes, no, on et off de la même façon. TOML 1.0 vise, selon ses propres objectifs, à être un format de configuration minimal, facile à lire en raison d'une sémantique évidente et se transposant sans ambiguïté vers une table de hachage ; il possède des commentaires, des types explicites (chaîne de caractères, entier, nombre à virgule flottante, booléen, date et heure), des tables entre crochets, des clés à points et des tables en ligne censées tenir sur une seule ligne.

Pourquoi c'est important

Un fichier de configuration est écrit par des personnes et lu par des programmes ; le format détermine à quel bout les erreurs se produisent. Les erreurs d'indentation et les conversions de type silencieuses forment la classe d'erreurs propre à YAML (version: 1.10 devient le nombre 1.1, un code pays NO devient false dans un chargeur 1.1) ; l'absence de commentaires et les clés dupliquées forment la classe d'erreurs propre à JSON ; TOML impose de longs chemins de table en cas d'imbrication profonde.

Comment l'appliquer

• Machine à machine (API, caches, export) : JSON, vérifié par rapport à un schéma JSON.
• Configuration entretenue à la main, avec une structure plate à moyenne : TOML — Python (pyproject.toml), Rust (Cargo) et de nombreux outils l'utilisent.
• YAML là où l'écosystème l'impose (pipelines CI, Kubernetes, Compose) : citer les chaînes de caractères qui ressemblent à des nombres, des booléens ou des dates ; choisir un chargeur conforme au schéma de base 1.2 ; ne pas charger de balises personnalisées.
• Quel que soit le format, transposer le résultat analysé dans un modèle typé, rejeter les clés inconnues et interrompre le traitement avec un message clair (fichier, ligne, clé).
• En cas de changement de format, convertir avec un outil et comparer le résultat analysé des deux fichiers, pas le texte.

Pièges

Un analyseur JSON peut, selon la RFC, accepter des extensions ; des commentaires ou des virgules finales qu'un outil tolère font échouer le suivant. Les ancres YAML et les documents multiples sont difficiles à vérifier pour des personnes. Les tables en ligne de TOML ne tolèrent pas de virgule finale. 1e3 est un nombre à virgule flottante dans le schéma de base de YAML 1.2, mais une chaîne de caractères dans les chargeurs 1.1 — une raison de plus de citer les valeurs.