JSON à TOML : convertissez les fichiers de configuration de la bonne manière

La première fois que TOML m'a mordu, ce n'était pas la syntaxe C'était l'ordonnancement J'avais un objet de paramétrage JSON d'un ancien service Node, je le voulais comme un config.toml pour une réécriture Rust, et j'ai fait ce que tout le monde fait la première fois : j'ai tapé les tables à la main Dix minutes plus tard l'analyseur lançait une erreur que je ne comprenais pas, pointant une ligne qui semblait parfaitement bien Le problème était trois touches assises en dessous d'un [table] en-tête qui appartenait au-dessus de lui TOML a une règle que JSON ne fait pas, et une fois que vous trébuchez dessus vous ne l'oubliez jamais.

je construis Toolz.dev« , et j'y ai expédié une longue étagère de convertisseurs de format, j'ai donc écrit le convertisseur JSON vers TOML pour supprimer toute cette catégorie d'erreur. Vous collez JSON, vous obtenez TOML qui réanalyse les mêmes données, et la commande est gérée pour vous. Ce guide est la chose que j'aurais aimé lire cet après-midi-là : qu'est-ce que TOML, où JSON et TOML ne sont pas d'accord, et comment convertir entre eux sans perdre quoi que ce soit qui vous intéresse. ».

tl;dr : TOML est un format de configuration typé utilisé par Cargo, Poetry, Hugo et beaucoup d'outils Rust and Go La conversion de JSON en TOML est principalement mécanique, mais trois choses nécessitent un jugement : l'ordre des tables (les touches avant les sous-tables, toujours), la façon dont vous écrivez des tableaux d'objets (tableaux de tableaux par rapport aux tableaux en ligne) et ce qui arrive à JSON null[TRADUCTION], que TOML n'a aucun moyen d'exprimer Le Convertisseur JSON à TOML rend les trois explicites et s'exécute entièrement dans votre navigateur.

Qu'est-ce que TOML, et pourquoi y convertirais-je JSON ?

TOML signifie Tom&#39 ; s Obvious, Minimal Language Il se lit comme un ancien fichier INI, mais contrairement à INI, il a une spécification réelle avec des valeurs typées, des dates de première classe et une grammaire définie Cette spécification est la raison pour laquelle il a gagné : un format de configuration qu'une personne peut lire en un coup d'œil, qu'une machine analyse de la même manière à chaque fois, sans ambiguïté quant à savoir si port = 8080 est une chaîne ou un nombre C'est un nombre, parce que TOML le dit.

Vous atteignez la conversion JSON en TOML lorsqu'une machine vous a donné JSON et qu'un outil veut TOML. Cela se produit plus que vous ne le pensez Une API renvoie un blob de paramètres en tant que JSON et vous en avez besoin pyproject.toml. Vous avez un vieux config.json et vous déplacez le projet vers une pile qui lit config.toml. Vous avez généré des données par programme, elles sont sorties sous le nom de JSON parce que c'est ce qui se passe JSON.stringify produit, et le consommateur est Cargo ou Hugo ou un service Go utilisant une bibliothèque TOML Dans tous les cas les données sont identiques Seule la sérialisation diffère.

Le sens inverse existe aussi, mais c'est un travail différent Si vous allez dans l'autre sens, le Formateur JSON cela vaut la peine d'être ouvert à la raison : vérifiez d'abord le JSON, et le Convertisseur JSON en YAML couvre l'autre format de configuration commun Ce guide concerne JSON entrant dans TOML.

Comment le convertisseur mappe-t-il JSON sur TOML ?

Il n'y a qu'une poignée de formes dans JSON, et chacune a une maison dans TOML. Comprendre la cartographie est avant tout comprendre l'outil.

UN JSON objet devient un TOML tableau. L'objet de niveau supérieur est la table racine, c'est pourquoi le convertisseur insiste pour que l'entrée soit un objet. Les objets imbriqués deviennent [table] en-têtes avec un chemin en pointillés, donc { "database": { "pool": { "max": 10 } } } devient un [database.pool] section avec max = 10 à l'intérieur de celui-ci.

UN JSON tableau d'objets devient un TOML tableau de tableaux: écrit avec le double support [[name]] en-tête, un bloc par élément C'est le modèle de TOML idiomatique pour une liste d'enregistrements : une liste de serveurs, une liste de dépendances, une liste de cibles de build Chaque élément obtient son propre [[servers]] bloc.

Chaque scalaire maps directement Une chaîne JSON devient une chaîne de base TOML en guillemets doubles, avec des caractères de contrôle échappés Un nombre JSON devient un entier TOML s'il s'agit d'un nombre entier et d'un float sinon Un booléen JSON devient true ou false. Ce sont les cas faciles, et le convertisseur ne se trompe jamais.

UN JSON tableau de scalaires devient un tableau en ligne TOML : ["admin", "editor"] reste ["admin", "editor"]. Les tableaux mixtes et les tableaux imbriqués sont également écrits en ligne, car c'est le seul endroit où ils s'adaptent.

Pourquoi l'ordre des clés compte-t-il autant dans TOML ?

C'est la règle qui attrape tout le monde, donc il vaut la peine d'être clairement indiqué Dans TOML, dans n'importe quelle table, toutes ces paires de clés/valeurs n°39 ; ses propres paires clé/valeur doivent apparaître avant l'un de ses en-têtes de sous-table Si vous écrivez un [server] en-tête, puis quelques clés, puis une autre clé qui appartient à la table racine, l'analyseur lit cette clé parasite dans le cadre de [server] au lieu de cela. Dans le meilleur des cas, il atterrit au mauvais endroit ; dans le pire des cas, le fichier ne parvient pas à analyser.

JSON n'a pas une telle règle Dans JSON, l'ordre des clés n'est même pas significatif, et les objets et les scalaires s'intermixent librement à l'intérieur des mêmes accolades Donc une conversion naïve JSON-to-TOML qui fait marcher l'objet dans l'ordre d'insertion et émet chaque clé au fur et à mesure produira du TOML cassé au moment où un scalaire suit un objet imbriqué.

Le convertisseur résout cela en faisant deux passages sur chaque table D'abord il émet toutes les touches simples, les scalaires et les tableaux en ligne Ce n'est qu'alors qu'il émet les en-têtes de sous-table et de tableau de tables, récurrents dans chacun Votre ordre de clé est conservé au sein de chaque groupe, ce que vous voulez, mais le réarrangement requis entre les deux groupes se produit automatiquement Vous n'avez jamais à y penser, et vous n'obtenez jamais l'erreur que j'ai eue.

Quand les tableaux d’objets doivent-ils être des tableaux plutôt qu’en ligne ?

Voici le seul choix authentique Un tableau d'objets peut être écrit de deux manières dans TOML, et les deux sont valides.

Le premier est un tableau de tableaux[TRADUCTION], la forme à double parenthèse Elle est verbeuse et lisible, un bloc par enregistrement, et c'est à cela que ressemble la plupart des TOML dans la nature Si vous avez vu un Cargo.toml avec plusieurs [[bin]] entrées, vous avez vu ceci.

[[servers]]
name = "web"
ip = "10.0.0.1"

[[servers]]
name = "api"
ip = "10.0.0.2"

La seconde est une tableau en ligne à l’intérieur d’un tableau normal, qui regroupe chaque objet sur une seule ligne.

servers = [
  { name = "web", ip = "10.0.0.1" },
  { name = "api", ip = "10.0.0.2" },
]

Les deux aller-retour aux mêmes données Lequel vous voulez dépend de la cible et du goût Les tableaux de tableaux se lisent mieux pour les enregistrements qu'un humain modifiera, et ils sont la convention pour la plupart des config d'outillage Les tableaux en ligne sont plus compacts et plus proches de la forme du JSON original, que certaines personnes préfèrent lorsque la liste est courte ou que les objets sont minuscules Le convertisseur se réfère par défaut aux tableaux de tableaux et vous donne une bascule pour changer Si vous n'êtes pas sûr, laissez-le par défaut : c'est à quoi ressemble habituellement un fichier TOML.

Qu'arrive-t-il à JSON null dans TOML ?

TOML n'a pas de null. Il n'y a pas de mot-clé, pas de valeur vide, rien. Il s’agit d’une décision de conception délibérée du format, et c’est le seul endroit où JSON à TOML est véritablement avec perte.

Donc le convertisseur doit faire un choix, et il vous permet de le faire Par défaut, une clé dont la valeur est null est abandonné, et l'outil liste les touches abandonnées dans une note sous la sortie donc rien ne disparaît silencieusement Si vous préférez garder la clé, vous pouvez passer à l'écriture null comme une chaîne vide, qui préserve la clé au prix de changer son type Ni l'un ni l'autre n'est parfait, car il n'y a pas de réponse parfaite Ce qui compte c'est que le choix soit visible plutôt qu'enterré.

Les nuls à l'intérieur des tableaux sont toujours supprimés, avec un avertissement, car un tableau TOML ne peut pas du tout contenir de null. Si votre JSON l'a fait [1, null, 3][TRADUCTION], le TOML sera [1, 3] et l'outil vous dira qu'il en a supprimé un. Si ces valeurs nulles ont une signification, c'est un signal pour remodeler les données avant de les convertir plutôt qu'après.

Pourquoi mon nombre a-t-il perdu sa décimale, ou en a-t-il gagné une ?

Celui-ci surprend les gens qui se soucient des types JSON ne distingue pas 5 de 5.0. Les deux analysent le même double IEEE 754, et à ce moment-là JSON.parse est fait il n'y a pas de trace du zéro traînant Donc quand le convertisseur voit le nombre 5: ce n’est pas une façon de savoir que vous vouliez dire un flotteur, et depuis 5 est un nombre entier il écrit un entier TOML.

TOML, en revanche, distingue les entiers des flotteurs, et certains outils se soucient de la différence. Si vous avez besoin d'une valeur tapé en float, le correctif est de lui donner une partie fractionnaire dans la source, 5.1 ou 5.0 écrit d'une manière qui survit, ou pour éditer la valeur unique après conversion C'est un changement d'un caractère et c'est rare, mais il vaut la peine de savoir pourquoi cela se produit plutôt que de supposer que le convertisseur est faux Ce n'est pas mal JSON a simplement jeté l'information avant que le convertisseur ne l'ait jamais vue.

Le cas inverse apparaît avec des nombres très grands ou très petits, où JavaScript&#39 ; s String() produit une notation d'exposant comme 1e+21. TOML accepte cela comme un flotteur, donc il convertit fin, mais la forme du nombre peut paraître différente de ce que vous avez tapé Encore une fois, la valeur est identique ; seul le rendu a changé.

Comment fonctionnent les clés nues et citées ?

TOML laisse une clé être écrite nue si elle est faite uniquement de lettres, chiffres, traits de soulignement et tirets Tout le reste, une clé avec un point, un espace, une barre oblique, un caractère Unicode, doit être cité Le convertisseur vérifie chaque clé et ne cite que celles qui en ont besoin, donc user-name reste nu et "user.name" obtient des citations pour empêcher le point d'être lu comme un chemin de table Vous n'avez pas à penser à cela, mais si vous voyez des citations autour d'une clé dans la sortie, c'est pourquoi : la clé contenait un caractère qui autrement changerait sa signification.

Un exemple travaillé

Voici l'échantillon que l'outil charge, pour que vous puissiez voir chaque règle à la fois Le JSON :

{
  "title": "Toolz config",
  "version": 2,
  "enabled": true,
  "owner": { "name": "Liton", "roles": ["admin", "editor"] },
  "database": { "host": "localhost", "port": 5432, "pool": { "min": 2, "max": 10 } },
  "servers": [
    { "name": "web", "ip": "10.0.0.1" },
    { "name": "api", "ip": "10.0.0.2" }
  ]
}

devient TOML où les scalaires racine viennent en premier, les objets imbriqués deviennent des tables pointillées dans l'ordre et le tableau de serveurs devient deux [[servers]] blocs :

title = "Toolz config"
version = 2
enabled = true

[owner]
name = "Liton"
roles = ["admin", "editor"]

[database]
host = "localhost"
port = 5432

[database.pool]
min = 2
max = 10

[[servers]]
name = "web"
ip = "10.0.0.1"

[[servers]]
name = "api"
ip = "10.0.0.2"

Remarquez que title, version et enabled sont écrits avant tout en-tête, roles reste un tableau en ligne car il s'agit d'un tableau de chaînes, et [database.pool] s'assoit sous [database] comme un chemin en pointillés Chaque règle de ce guide est visible dans neuf lignes de sortie.

Quel outil pour quelle conversion ?

TOML est un format dans une famille, et le bon outil dépend de l'endroit où vous commencez et terminez Voici comment j'y pense.

Vous avez	tu veux	manier
JSON	Configuration TOML	JSON à TOML
JSON	Configuration YAML	JSON vers Yaml
banane	JSON	YAML à JSON
JSON	XML	JSON vers XML
Messy JSON	Lisible JSON	Formateur JSON

Le modèle est que les formats de configuration sont des vues interchangeables des mêmes données, et le convertisseur que vous souhaitez est nommé en fonction de la direction dans laquelle vous allez TOML, YAML et JSON expriment tous des données clés/valeurs imbriquées ; la différence est celle que lit votre outil cible.

Est-il sécuritaire de convertir un fichier de configuration en ligne ?

Les fichiers de configuration sont exactement le genre de chose que vous devriez faire attention à coller dans un site Web, car ils contiennent souvent des chaînes de connexion, des jetons et d'autres secrets. Le Convertisseur JSON à TOML fonctionne entièrement dans votre navigateur Le JSON que vous collez est analysé en mémoire sur votre appareil, le TOML y est produit, et rien n'est envoyé à un serveur, écrit dans un journal ou stocké Vous pouvez regarder cela vous-même : ouvrez votre onglet réseau, exécutez une conversion, et voyez qu'aucune requête ne s'éteint Il continue également à fonctionner sans connexion une fois la page chargée, ce qui est la preuve pratique que le travail est local Si vous vous souciez de l'endroit où vont vos données, et avec un fichier de configuration vous devriez, c'est la propriété qui compte C'est le même principe derrière chaque outil du site, et la raison pour laquelle j'en ai longuement écrit dans la note sur Confidentialité des données dans les outils en ligne.

Où cela s'inscrit dans un véritable flux de travail

La conversion de format est rarement la tâche entière C'est une étape Vous tirez un objet de paramètres hors d'une API, vous le convertissez, vous le déposez dans un projet La valeur d'un convertisseur côté client est qu'il se glisse dans ce flux sans friction : pas de téléchargement, pas de compte, pas d'attente sur un serveur, pas de se demander si vos secrets sont maintenant dans les journaux de quelqu'un&#39 ; c'est la même raison pour laquelle je garde le tout Toolz.dev définissez le côté client, et c'est un thème sur lequel je reviens dans le Outils de productivité des développeurs écrivez-le, car les outils que vous atteignez vingt fois par jour sont ceux où s'additionnent un aller-retour de deux secondes et une question de confidentialité.

TOML a gagné sa place dans ce flux en étant ennuyeux de la meilleure façon Il analyse la même chose partout, il lit bien, et son seul bord tranchant, la règle de commande, est exactement le genre de chose qu'un convertisseur devrait déposer pour vous Coller votre JSON, choisir comment vous voulez que les tableaux et les nuls soient traités, et copier TOML qui fonctionne juste.

Questions fréquentes

Comment convertir JSON en TOML ?

Collez votre objet JSON dans le convertisseur et cliquez sur Convertir L'outil sérialise les objets dans les tables TOML, les tableaux d'objets dans les tableaux de tables et toutes les autres valeurs en ligne, puis vous donne un TOML standard à copier. Le JSON de niveau supérieur doit être un objet, car un document TOML est toujours une table.

Dans quel cas TOML est-il utilisé ?

TOML est un format de fichier de configuration conçu pour être facile à lire et sans ambiguïté à analyser C'est le format de configuration pour Rust&#39 ; s Cargo (Cargo.toml), Python packaging (pyproject.toml), Hugo, et de nombreux outils Go et Rust Les gens convertissent JSON en TOML pour transmettre une configuration générée par machine à un outil qui attend TOML.

Qu'arrive-t-il aux valeurs nulles JSON dans TOML ?

TOML n'a pas de type null, donc un JSON null ne peut pas être représenté directement Par défaut ce convertisseur laisse tomber les clés nulles et ajoute une note les listant ; vous pouvez passer à l'écriture en tant que chaînes vides à la place Les nuls à l'intérieur des tableaux sont toujours supprimés, car un tableau TOML ne peut pas contenir de null.

Quelle est la différence entre un tableau de tableaux et un tableau en ligne ?

Un tableau de tables utilise des en-têtes répétés à double parenthèse, un bloc par enregistrement, et constitue le moyen idiomatique TOML d'écrire une liste d'objets tels qu'une liste de serveurs ou de dépendances. Une table en ligne regroupe un objet sur une ligne sous la forme d'un ensemble de clés égale les paires de valeurs en accolades. Cet outil est par défaut un tableau de tables mais vous permet de choisir en ligne à la place.

Pourquoi mon numéro JSON 5.0 est-il devenu 5 dans TOML ?

JSON ne préserve pas la différence entre 5 et 5.0, donc l'analyse se lit à la fois comme le nombre 5 Puisque 5 est un nombre entier, le convertisseur l'écrit comme un entier TOML. Si vous avez besoin qu'il soit tapé comme un float, ajoutez une partie fractionnaire dans la source ou modifiez la valeur unique après conversion.

Le convertisseur garde-t-il mon ordre de clé ?

Oui. Les clés sont émises dans l'ordre dans lequel elles apparaissent dans le JSON, avec un réarrangement requis : dans chaque table, les clés simples sont écrites avant tout en-tête de sous-table ou de tableau de tables. Il s'agit d'une règle de syntaxe TOML, pas d'un choix de réorganisation, et sans elle, le fichier ne serait pas analysé.

Mon JSON est-il téléchargé sur un serveur ?

Non. La conversion complète se produit dans votre navigateur à l'aide de JavaScript simple. Votre JSON, y compris les secrets ou informations d'identification d'un fichier de configuration, n'est jamais transmis, enregistré ou stocké, et le convertisseur continue de fonctionner sans connexion une fois la page chargée.

Pourquoi dit-il que le niveau supérieur doit être un objet ?

Un document TOML est défini comme une table, ce qui signifie qu'il doit partir d'un ensemble de paires clé/valeur Un tableau JSON ou scalaire nu n'a pas de table sur laquelle mapper Enroulez-le d'abord dans un objet, par exemple en plaçant votre tableau sous une clé nommée, et il convertira.