Convertir JSON en TOML

JSON n’a pas de commentaires. C’est inscrit dans la spécification plutôt que d’être un oubli, et c’est la raison unique pour laquelle la plupart des configurations écrites en JSON sont désagréables à maintenir : la raison pour laquelle un timeout vaut 45 secondes ne peut pas vivre à côté du 45. TOML, qui a mis huit ans de versions 0.x pour atteindre la 1.0 en janvier 2021 et qui est désormais le format de configuration de Cargo, pyproject.toml et Hugo, possède des commentaires, et c’est en général toute la motivation de cette conversion.

La seconde raison est la platitude. Une configuration JSON à trois niveaux de profondeur est trois niveaux d’accolades et beaucoup d’indentation ; la même chose en TOML est une ligne d’en-tête lisant [server.tls.client] et une courte liste de clés en dessous. Rien dans la donnée n’a changé, mais le diff qu’une relectrice voit quand une valeur bouge est une ligne au lieu d’un bloc réindenté.

Un document TOML est une table. Il ne peut pas commencer par un tableau comme le peut un document JSON, si bien qu’un fichier dont le premier caractère est un crochet carré n’a rien sur quoi s’appuyer. La conversion gère cela plutôt que d’échouer : une valeur qui n’est pas un objet est enveloppée sous une clé nommée items, et la sortie commence par [[items]].

Cela garde le fichier valide, et c’est un placeholder plutôt qu’une réponse. Aucun convertisseur ne peut savoir si l’outil qui lira le fichier attend que cette liste s’appelle dependencies, servers ou plugins. Renommez la clé sur la première ligne et le reste du fichier est déjà correct — c’est une édition d’un mot, et elle est délibérément évidente plutôt que cachée.

C’est la défaillance à vérifier à chaque fois. TOML n’a pas de littéral null, et l’écriture n’en invente pas : une clé dont la valeur JSON était null n’est tout simplement pas écrite. Convertissez {"a": null} et la sortie est un fichier vide. Convertissez une table contenant une vraie clé et une clé null, et seule la vraie clé apparaît.

Si cela importe, cela dépend entièrement de l’outil qui lira le résultat. Beaucoup d’analyseurs de configuration traitent une clé absente et une clé null de la même manière — les deux retombent sur une valeur par défaut — et pour ceux-là rien n’a été perdu. D’autres les distinguent, et là la conversion a silencieusement modifié la configuration. La défense consiste à chercher les null dans le JSON avant de convertir plutôt qu’à comparer les deux fichiers après, parce qu’une ligne absente est bien plus difficile à remarquer qu’une ligne modifiée.

C’est la partie qui surprend en général celles et ceux qui s’attendent à ce que TOML soit un format plus faible que JSON. Une liste d’enregistrements s’exprime par le même en-tête de table répété : [[servers]] trois fois donne trois serveurs, chacun avec ses propres clés en dessous. C’est plus verbeux qu’un tableau JSON et considérablement plus facile à éditer, parce qu’ajouter un quatrième serveur consiste à copier cinq lignes plutôt qu’à équilibrer des crochets.

Les membres ne doivent pas se ressembler. Un tableau où le premier objet a un id et un name et où le second ajoute un region convertit sans se plaindre, et le TOML reste valide — chaque bloc porte les clés qu’il a. C’est un avantage réel sur les cibles tabulaires de ce site, où un tableau hétérogène doit être réconcilié en un seul ensemble de colonnes avant que quoi que ce soit puisse être écrit.

Un en-tête de table TOML s’approprie tout ce qui est écrit en dessous jusqu’à l’en-tête suivant. Cela signifie qu’une clé nue placée après [server] appartient à server, quoi qu’ait voulu l’autrice ou l’auteur. L’écriture hisse donc toutes les clés scalaires de premier niveau au-dessus du premier en-tête de table : {"server": {"host": "localhost"}, "debug": true} ressort en debug = true, une ligne vide, puis [server] et host.

La sortie n’est donc pas dans l’ordre où votre JSON était, et elle ne peut pas l’être. C’est le seul réordonnancement qui préserve le sens, et n’importe quel autre modifierait la table à laquelle appartient une clé. Si le regroupement d’origine avait son importance pour la lisibilité, restaurez-le en déplaçant des blocs de table entiers — cela est sûr — plutôt qu’en déplaçant des clés isolées au-dessus ou en dessous d’un en-tête.

Quatre niveaux d’imbrication JSON deviennent une seule ligne d’en-tête : {"a":{"b":{"c":{"d":1}}}} convertit en [a.b.c] avec d = 1 en dessous. TOML exprime la profondeur dans l’en-tête plutôt que dans l’indentation, ce qui fait qu’une configuration profondément structurée est souvent plus courte et plus plate en TOML que dans le JSON d’où elle vient.

Cela a aussi une limite qui tient au goût plutôt qu’à la validité. Un en-tête comme [build.targets.linux.arm64.flags] est légal et personne n’aime le lire. Si le fichier converti présente des en-têtes au-delà de trois ou quatre segments, c’est en général le signe que la configuration mérite d’être éclatée en plusieurs fichiers ou plusieurs outils, et la conversion vient de rendre visible un problème qui existait déjà.

La sortie ne porte aucun commentaire, parce que l’entrée n’avait nulle part où en garder. JSON n’en porte pas, donc il n’y a rien à traduire — ce n’est pas un manquement du convertisseur mais la raison pour laquelle le JSON méritait d’être quitté.

Ce qui rend les cinq premières minutes après la conversion comme la partie la plus précieuse de l’exercice. Le fichier TOML est la version de cette configuration qui peut porter la mémoire institutionnelle à son sujet : quelles valeurs peuvent être modifiées sans danger, laquelle doit correspondre à une valeur dans un autre dépôt, pourquoi une limite est fixée là où elle l’est. Cette connaissance existe dans la tête de quelqu’un ou dans un message de commit aujourd’hui, et c’est le moment où l’écrire dans le fichier ne coûte rien.

TOML dispose de quatre types de date et d’heure, dont un date-time avec décalage qui est une valeur de premier ordre plutôt qu’une chaîne. JSON n’en a aucun : RFC 8259 donne des chaînes, des nombres, des booléens, null, des tableaux et des objets, et chaque horodatage dans chaque fichier JSON du monde est l’un des deux premiers par convention.

Donc une valeur JSON de « 2024-01-01T00:00:00Z » est écrite en chaîne TOML entre guillemets, ce qui est correct et n’est pas ce que le format pourrait exprimer. Si l’outil qui lira le fichier veut un vrai date-time, retirez les guillemets à la main sur ces lignes. Elle s’analyse ensuite comme une date, et rien d’autre dans le fichier n’a à changer.

La vérification la plus économique est l’aller-retour : convertissez le TOML en JSON et comparez avec ce dont vous êtes parti. Les clés qui tenaient null seront absentes et rien d’autre ne devrait différer, ce qui transforme une inquiétude vague en un diff lisible en quelques secondes.

La seconde vérification est l’outil lui-même. Cargo, Hugo et la plupart des outils de packaging Python vous diront immédiatement si le document s’analyse et si les clés sont là où ils les attendent, et cela attrape la chose qu’un aller-retour ne peut pas attraper : un fichier correctement converti dont la clé de premier niveau s’appelle encore items parce que personne ne l’a renommée.

Dans l’onglet de votre navigateur, sur votre propre processeur. Les deux moitiés sont en JavaScript — l’analyseur JSON est celui intégré au navigateur, et l’écriture TOML est une petite bibliothèque chargée à la demande — si bien qu’aucune requête ne transporte le fichier ailleurs, et il n’y a ni compte, ni file d’attente, ni quota journalier. Le niveau gratuit accepte les fichiers jusqu’à 100 Mo, ce que pour de la configuration n’est une limite qu’aucune n’atteint.

Cela compte davantage pour de la configuration que pour la plupart des données. Un fichier de configuration JSON est exactement le type de chose qui contient des noms d’hôtes internes, des noms de buckets, des comptes de service et, à l’occasion, un identifiant que quelqu’un voulait retirer, et le téléverser sur un convertisseur web serait la partie qui serait réellement contraire à la politique. Ici, il n’y a rien à téléverser.