Convertir TOML en YAML

TOML et YAML couvrent le même terrain. Les deux sont des formats de configuration en texte clair, structurés en paires clé-valeur, supportant l’imbrication, les tableaux, les scalaires typés et les chaînes multi-lignes. La conversion d’un arbre à l’autre est une réécriture, pas une transformation : aucune information ne quitte le document.

C’est la raison pour laquelle cette page est inhabituellement courte sur les pertes et longue sur les différences de style. YAML 1.2 traite JSON comme un sous-ensemble et hérite de la même tolérance vis-à-vis des nombres, des booléens et des chaînes ; TOML est plus strict et plus explicite. Passer d’un format strict à un format permissif ouvre des cas où une valeur qui était clairement typée devient ambiguë à la lecture, et c’est ce que les sections qui suivent décrivent.

Un en-tête entre crochets devient un mapping YAML, écrit avec deux espaces d’indentation et les clés en colonne alignée ou non selon ce qui a le mieux arrangé l’auteur. Un en-tête pointé `database.connection` devient un mapping `database` contenant un mapping `connection`, exactement la même imbrication que dans le header. Un header à double crochets, qui était un array of tables, devient une liste YAML de mappings, avec un tiret par entrée et l’ordre du document conservé.

L’ordre des clés est préservé, ce qui est la propriété qu’aucun des deux formats ne garantit mais qu’un auteur attend. Un diff entre deux conversions n’est un vrai diff que si le contenu a changé, pas si l’ordre a changé, et garder l’ordre est la seule manière de le garantir. La sortie est indentée de deux espaces et se termine par un retour à la ligne, ce qui est ce que la plupart des linters YAML et des outils de revue attendent.

TOML a de vrais types temporels dans sa spécification : offset datetimes, local datetimes, local dates et local times. YAML 1.2 n’a qu’un type chaîne ; la balise de timestamp YAML existe, mais elle appartient au schéma de types 1.1 que la plupart des lecteurs modernes n’activent pas. Résultat : un datetime TOML arrive en YAML comme une chaîne, et la chaîne est exactement ce qui a été lu.

Pour qu’un destinataire qui interprète YAML 1.1 voie une date, mettre la valeur entre guillemets dans la sortie est la seule manière d’être certain du résultat. La conversion le fait systématiquement pour les valeurs qui contiennent un T ou un tiret en position de date, parce que c’est la convention qu’une valeur non quotée comme `2024-01-01` sera lue comme un timestamp par certains chargeurs. Pour les valeurs qui n’ont pas cette forme — un offset datetime complet, par exemple — l’auteur laisse la chaîne nue et c’est à vous de décider si le consommateur l’interprétera correctement.

TOML écrit `true` et `false` comme booléens, et c’est ce qui sort en YAML. Aucun risque de ce côté. Le risque vient de l’autre sens : une valeur TOML qui est la chaîne `yes`, `no`, `on` ou `off` est une chaîne pour TOML, et la conversion la laisse nue parce que c’est une chaîne YAML valide. Mais PyYAML, qui est ce qu’utilisent Ansible et un grand nombre d’outils Python, lit YAML 1.1 et résout ces mots en booléens.

C’est la même embuscade que sur la page JSON vers YAML, et la parade est la même : la conversion met entre guillemets les chaînes qui seraient lues autrement. Cela vaut pour `yes`, `no`, `on`, `off`, `true`, `false` quand la valeur TOML a des guillemets explicites autour, pour `null` quand la valeur TOML est la chaîne `null`, et pour toute chaîne qui ressemble à un nombre ou à une date. Le résultat est sans ambiguïté pour un lecteur 1.2 et correct pour un lecteur 1.1 qui respecte la mise entre guillemets.

TOML permet les chaînes multi-lignes avec un bloc à triple guillemet, et la conversion les réécrit en YAML avec un caractère pipe et le texte indenté sur ses propres lignes. Un script shell de douze lignes arrive sous forme de douze lignes dans le fichier YAML, et un reviewer peut le lire au lieu de compter des backslash-n.

C’est l’une des vraies raisons de préférer YAML pour les fichiers qu’une équipe va éditer à la main. Pour les chaînes courtes, la différence est invisible. Pour les longues, c’est la différence entre un fichier que les gens ouvrent et un fichier qu’ils n’ouvrent jamais, et c’est précisément la qualité qui décide si un format de configuration survit à l’équipe qui l’a créé.

TOML supporte des entiers 64 bits ; YAML, comme JSON, ne représente les nombres que comme des flottants IEEE, exacts jusqu’à environ neuf trillions. Un grand identifiant — un snowflake, un horodatage nanoseconde en entier, un numéro de série — est écrit comme une chaîne par la conversion, parce que le mettre en nombre serait promettre une exactitude que la sortie ne peut pas tenir.

Refuser la conversion pour ces valeurs était une option, et elle a été rejetée : un identifiant tronqué est un bogue qui se manifeste dans une jointure des semaines plus tard, et le coût de mettre la valeur entre guillemets à la main dans le TOML source est d’une minute. La conversion le fait pour vous plutôt que de vous laisser le soin de le découvrir.

TOML supporte les commentaires. YAML les supporte aussi, mais aucun convertisseur automatique ne peut les transporter, parce qu’un commentaire est un élément de la grammaire, pas un attribut d’une valeur. Un `# raison de cette épingle : CVE-2024-1234` disparaît.

Recopier les commentaires à la main est la seule voie. Pour un pyproject.toml de cent lignes c’est quinze minutes, pour un Cargo.toml de mille lignes c’est un après-midi, et c’est un coût qui mérite d’être budgété avant la conversion. Pour un fichier destiné à être lu, généré puis oublié, c’est un coût nul et l’absence ne se voit pas. Pour un fichier destiné à vivre, c’est l’investissement qui distingue un dépôt maintenu d’un dépôt qui n’est plus lu.

L’ordre des clés est préservé, ce qui garde un diff entre deux conversions signifiant quelque chose. Un manifest Kubernetes dont les clés sont réordonnées ressemble à un changement majeur même quand rien n’a bougé, et la conversion s’efforce de ne pas être la source de cette confusion.

L’unique exception est les clés qui sont des chaînes numériques : une clé TOML `“2024”` est réordonnée en tête de son mapping et triée en ascendant, parce que c’est ainsi que YAML et JavaScript ordonnent les clés de type entier. C’est le seul endroit où la sortie ne se lit pas dans le même ordre que la source, et c’est un comportement qui ne concerne qu’une minorité de configurations mais qu’il vaut la peine de nommer.

YAML permet de définir un bloc une fois et de le référencer ailleurs avec une ancre et un alias, ce qui est largement utilisé dans les fichiers compose et certains manifests Kubernetes. TOML n’a aucune notion d’ancre ou d’alias, et la conversion ne peut pas en inventer, parce que la décision de ce qui mérite d’être ancré est éditoriale et non structurelle.

Donc un fichier TOML qui répète la même structure de configuration dans plusieurs contextes arrive en YAML avec la répétition intacte. Refactoriser avec des ancres est une édition à faire dans le YAML produit, et c’est une édition qui n’est rentable que sur des répétitions réelles. Pour un fichier de configuration qui se lit, la répétition est honnête ; pour un fichier qui se génère, c’est un candidat à un template plutôt qu’à une conversion.

La conversion est un parcours d’arbre en mémoire. Le TOML est lu par un parseur chargé à la demande, l’arbre intermédiaire est construit en JavaScript, et le YAML est écrit par un sérialiseur. Aucun de ces trois modules n’adresse le réseau, et le convertisseur ne charge rien d’autre que ce qu’il faut pour cette tâche.

Pour un Cargo.toml de crate interne ou un pyproject.toml d’un paquet non publié, c’est une garantie qui compte. Le fichier peut nommer des dépendances privées, un registre interne, des chemins de déploiement, et le laisser partir vers un service tiers n’est pas une opération qu’une équipe consciente de sa chaîne d’approvisionnement fait par hasard. Ici, il n’y a personne à qui le faire fuiter. Le plafond gratuit de 100 Mo est bien au-delà de ce que n’importe quel fichier de configuration pèse jamais, et le résultat est prêt à être validé localement avant d’être validé à distance.