Convertir TOML en JSON

TOML est le standard pour le packaging Python et Rust depuis des années, et l’outillage autour d’un dépôt n’a souvent pas suivi. Une étape de CI avec jq disponible et rien d’autre, un script Node qui doit lire la version dans un Cargo.toml, un tableau de bord qui inventorie les dépendances dans deux cents dépôts — tous peuvent lire du JSON et aucun ne peut lire du TOML sans une nouvelle dépendance.

C’est le cas que cette conversion sert, et cela marche proprement parce que les deux modèles de données se chevauchent presque entièrement. TOML est une table de paires clé-valeur avec imbrication et tableaux, ce qui est un objet JSON avec imbrication et tableaux. Les parties intéressantes sont les quatre endroits où TOML sait quelque chose que JSON ignore.

Un header entre crochets devient un objet imbriqué, et un header pointé devient une imbrication sur plusieurs niveaux — un header écrit pour un outil puis un linter en dessous produit un objet dans un objet, donc le chemin JSON correspond exactement au header. Rien dans la structure n’a besoin d’être interprété.

Un header à double crochets est l’array of tables, et il devient un tableau JSON d’objets avec une entrée par occurrence. C’est ce qui contient les auteurs d’un paquet Python, les binaires d’un crate Rust et les cibles d’un build, et c’est la construction dont les gens s’inquiètent le plus et dont ils ont le moins besoin de s’inquiéter. L’ordre est préservé.

TOML est le seul format de cette famille avec de vrais types temporels : offset datetimes, local datetimes, local dates et local times sont dans la spécification, et un parseur les renvoie comme des dates. JSON n’a pas de type date du tout, donc chacun devient une chaîne.

Les valeurs survivent avec un accroc. Un offset datetime garde son offset plutôt que d’être normalisé en UTC, ce qui est un meilleur comportement que plusieurs autres conversions sur ce site. Une local date arrive exactement comme écrite. Un local time gagne une composante milliseconde qu’il n’avait pas — une heure écrite huit heures du matin arrive avec une partie fractionnaire attachée. Si quelque chose en aval compare ces chaînes plutôt que de les parser, ce suffixe en plus est ce qui cassera la comparaison.

TOML 1.0 exige d’une implémentation qu’elle gère les entiers 64 bits signés. Les nombres JSON sont des doubles IEEE et ne sont exacts que jusqu’à environ neuf trillions. Un fichier TOML contenant un entier au-dessus de cette plage est entièrement légal, et le parseur ici s’arrête avec une erreur disant que l’entier ne peut pas être représenté sans perte plutôt que de produire du JSON avec un nombre faux dedans.

Refuser est la bonne décision et cela mérite d’être compris plutôt que contourné à l’aveugle. Un identifiant silencieusement arrondi est un bogue qui se manifeste des semaines plus tard dans une jointure qui ne correspond à rien. Si votre TOML contient une valeur de cette taille — un ID snowflake, un grand numéro de série, un horodatage nanoseconde comme entier — mettez-la entre guillemets comme chaîne dans la source. Ce n’était jamais une quantité, et la mettre entre guillemets rend tout consommateur en aval correct d’un coup.

Les flottants TOML incluent inf et nan comme valeurs littérales. JSON n’a ni l’un ni l’autre, et le sérialiseur écrit null pour les deux. C’est le comportement JavaScript standard et c’est destructeur d’une manière que rien ne signale — une limite supérieure configurée à l’infini et une limite non configurée deviennent la même chose dans le JSON.

La perte plus subtile est le typage. TOML distingue un entier d’un flottant, donc 1 et 1.0 sont des valeurs différentes avec des types différents, et un schéma ou une application peut s’y fier. JSON n’a qu’un type nombre, et 1.0 est sérialisé comme 1. Si un consommateur du JSON a besoin de savoir qu’une valeur a été déclarée comme flottant, cette information doit voyager par un autre canal, parce qu’elle n’est plus dans le fichier.

Les tables et les clés sortent dans l’ordre où TOML les a déclarées, ce qui garde un fichier converti lisible et garde un diff entre deux conversions signifiant quelque chose. La sortie est indentée de deux espaces et se termine par un retour à la ligne.

L’exception est les clés numériques. Une clé TOML entre guillemets qui est un nombre — ce qui apparaît dans des configs qui indexent des choses par année ou par port — est réordonnée avant toutes les autres clés de son objet et triée en ascendant, parce que c’est ainsi que les objets JavaScript ordonnent les clés de type entier. C’est le seul endroit où le JSON ne se lit pas dans le même ordre que la source.

La sortie est du JSON ordinaire, donc jq la lit sans drapeau : extraire une version de projet, lister des noms de dépendances ou vérifier qu’une section d’outil existe sont autant d’expressions d’une ligne. C’est en général toute la raison du détour, et cela transforme un script shell qui allait grepper un fichier TOML en un script qui l’interroge proprement.

Cela ouvre aussi la validation. JSON Schema est mature et largement implémenté, et TOML n’a pas de langage de schéma dans sa spécification, donc convertir puis valider est une vraie manière d’imposer des règles maison à travers de nombreux dépôts — chaque paquet doit déclarer une licence, chaque crate doit épingler son édition — qui ne peuvent pas être vérifiées contre le TOML directement.

TOML supporte les commentaires et les utilise abondamment : la raison pour laquelle une dépendance est épinglée, le numéro de ticket à côté d’un contournement, le bloc qui explique à quel environnement un réglage s’applique. JSON n’a pas de syntaxe de commentaire sous RFC 8259, donc rien de tout cela n’arrive.

Cela tranche la direction de la relation. Le TOML est le fichier que les gens éditent et révisent, et le JSON est généré à partir de lui chaque fois que quelque chose a besoin de le lire. Cocher le JSON dans le dépôt à côté du TOML crée deux versions de la vérité qui vont diverger ; le générer à l’étape de build ne le fait pas.

Si la lecture se passe à l’intérieur d’une application plutôt que dans une étape de build, utilisez un parseur. Chaque langage majeur en a un — Python a tomllib dans sa bibliothèque standard depuis plusieurs versions, et Rust, Go et JavaScript ont tous des options bien maintenues. Lire le fichier directement garde les types temporels et la distinction entier-flottant que cette conversion aplatit.

Le convertisseur gagne sa place à la frontière : une inspection ponctuelle, une étape de CI où ajouter une dépendance coûte plus que cela ne vaut, ou un pipeline dont l’étape suivante ne parle que JSON. Tout tourne dans votre navigateur, donc une config privée avec des identifiants dedans peut être déposée ici sans risque, et le plafond gratuit de 100 Mo est bien au-delà de tout fichier de configuration.