JSON in TOML: Konfigurationsdateien richtig konvertieren

Als TOML mich das erste Mal gebissen hat, war es nicht die Syntax, es war die Reihenfolge Ich hatte ein JSON Settings Objekt von einem alten Node Service, ich wollte es als config.toml Für eine Rust-Umschreibung, und ich tat, was jeder beim ersten Mal tut: Ich tippte die Tische von Hand. Zehn Minuten später warf der Parser einen Fehler, den ich nicht verstand, und zeigte auf eine Linie, die vollkommen in Ordnung aussah. Das Problem waren drei Tasten, die unter einem saßen [table] Kopfzeile, die darüber gehörte TOML hat eine Regel, die JSON nicht hat, und wenn man einmal darauf stolpert, vergisst man sie nie.

Ich baue Toolz.dev, und ich habe dort ein langes Regal von Formatkonvertern verschickt, also habe ich den JSON-zu-TOML-Konverter geschrieben, um diese ganze Kategorie von Fehlern zu entfernen. Wenn Sie JSON einfügen, erhalten Sie TOML, das erneut auf dieselben Daten parstet, und die Bestellung wird für Sie abgewickelt. Dieser Leitfaden ist das, was ich am Nachmittag gerne gelesen hätte: Was TOML ist, wo JSON und TOML anderer Meinung sind und wie man zwischen ihnen konvertiert, ohne etwas zu verlieren, das Ihnen am Herzen liegt.

tl; dr: TOML ist ein typisiertes Konfigurationsformat, das von Cargo, Poetry, Hugo und vielen Rust-and-Go-Werkzeugen verwendet wird. Die Konvertierung von JSON in TOML ist größtenteils mechanisch, aber drei Dinge erfordern eine Beurteilung: Tabellenreihenfolge (Schlüssel vor Untertabellen, immer), wie Sie Arrays von Objekten schreiben (Arrays von Tabellen versus Inline-Tabellen) und was mit JSON passiert null, die TOML nicht auszudrücken vermag Die JSON-TOML-Konverter Macht alle drei explizit und läuft komplett in Ihrem Browser.

Was ist TOML und warum sollte ich JSON in es umwandeln?

TOML steht für Tom' s Obvious, Minimal Language Sie liest sich wie eine alte INI-Datei, hat aber im Gegensatz zu INI eine echte Spezifikation mit eingegebenen Werten, erstklassigen Daten und einer definierten Grammatik Diese Spezifikation ist der Grund, warum sie gewonnen hat: ein Konfigurationsformat, das eine Person auf einen Blick lesen kann, das eine Maschine jedes Mal auf die gleiche Weise analysiert, ohne Unklarheiten darüber, ob port = 8080 String oder eine Zahl ist Es ist eine Zahl, denn TOML sagt.

Sie greifen zur JSON-zu-TOML-Konvertierung, wenn Ihnen eine Maschine JSON gegeben hat und ein Tool TOML will Das passiert mehr, als Sie denken würden Eine API gibt einen Einstellungsblob als JSON zurück und Sie brauchen ihn in pyproject.toml. Du hast ein altes config.json Und Sie verschieben das Projekt auf einen Stapel, der liest config.toml. Sie haben einige Daten programmgesteuert generiert, es kam als JSON heraus, weil das das ist JSON.stringify Produziert, und der Verbraucher ist Cargo oder Hugo oder ein Go-Dienst mit einer TOML-Bibliothek In jedem Fall sind die Daten identisch Nur die Serialisierung unterscheidet sich.

Die umgekehrte Richtung gibt es auch, aber es ist ein anderer Job Wenn du in die andere Richtung gehst, ist die JSON-Formater Es lohnt sich, offen zu sein, um zuerst das JSON und das zu überprüfen JSON-zu-YAML-Konverter Deckt das andere gängige Konfigurationsformat ab. In dieser Anleitung geht es darum, dass JSON in TOML vordringt.

Wie bildet der Konverter JSON auf TOML ab?

Es gibt nur eine Handvoll Formen in JSON, und jede hat ein Zuhause in TOML. Das Verständnis der Zuordnung ist das meiste, das Werkzeug zu verstehen.

EIN JSON Objekt TOML wird Tabelle. Das Objekt der obersten Ebene ist die Stammtabelle, weshalb der Konverter darauf besteht, dass die Eingabe ein Objekt ist Verschachtelte Objekte werden [table] Kopfzeilen mit einem gepunkteten Pfad, also { "database": { "pool": { "max": 10 } } } wird ein [database.pool] Abschnitt mit max = 10 Darin.

EIN JSON Array von Objekten TOML wird Tabellenarray, mit der Doppelklammer geschrieben [[name]] Header, ein Block pro Element Dies ist das idiomatische TOML-Muster für eine Liste von Datensätzen: eine Liste von Servern, eine Liste von Abhängigkeiten, eine Liste von Build-Zielen Jedes Element bekommt sein eigenes [[servers]] Block.

Jeder Skalar Karten direkt Eine JSON-Zeichenfolge wird in doppelten Anführungszeichen zu einer TOML-Basiszeichenfolge, wobei Steuerzeichen entgangen sind Eine JSON-Zahl wird zu einer TOML-Ganzzahl, wenn es sich um eine ganze Zahl handelt und ansonsten um einen Float. Ein JSON-Boolescher wird true oder false. Das sind die einfachen Fälle, und der Konverter versteht sie nie falsch.

EIN JSON Skalaranordnung TOML-Inline-Array wird: ["admin", "editor"] Aufenthalte ["admin", "editor"]. Gemischte Arrays und verschachtelte Arrays werden auch inline geschrieben, denn nur dort passen sie.

Warum spielt die Schlüsselbestellung in TOML eine so große Rolle?

Dies ist die Regel, die jeden fängt, also lohnt es sich, klar zu sagen In TOML, innerhalb jeder Tabelle, müssen alle diese Tabelle' eigene Schlüssel/Wert-Paare vor jedem ihrer Untertabellen-Header erscheinen Wenn Sie eine schreiben [server] Header, dann einige Tasten, dann eine weitere Taste, die zur Stammtabelle gehört, der Parser liest diese Streustaste als Teil von [server] Stattdessen. Best case landet es an der falschen Stelle; im schlimmsten Fall lässt sich die Datei nicht analysieren.

JSON hat keine solche Regel. In JSON ist die Schlüsselreihenfolge nicht einmal signifikant und Objekte und Skalare vermischen sich frei in denselben Klammern. Eine naive JSON-zu-TOML-Konvertierung, die das Objekt in Einfügungsreihenfolge abwickelt und jeden Schlüssel im Laufe der Zeit aussendet, erzeugt also gebrochenes TOML in dem Moment, in dem ein Skalar einem verschachtelten Objekt folgt.

Der Konverter löst das, indem er zwei Durchgänge über jede Tabelle macht, zuerst gibt er alle einfachen Tasten, die Skalare und Inline-Arrays ab, erst dann gibt er die Untertabellen - und Array-of-Tables-Header aus, die in jede Gruppe rekursiv gehen, innerhalb jeder Gruppe bleibt deine Schlüsselreihenfolge erhalten, was du willst, aber die erforderliche Neuordnung zwischen den beiden Gruppen geschieht automatisch, du musst nie darüber nachdenken, und du bekommst nie den Fehler, den ich bekommen habe.

Wann sollten Arrays von Objekten Tabellen versus Inline sein?

Hier ist die eine echte Wahl Ein Array von Objekten kann in TOML auf zwei Arten geschrieben werden, und beide sind gültig.

Das erste ist ein TabellenarrayDie Doppelklammernform. Sie ist wortreich und lesbar, ein Block pro Datensatz, und so sieht das meiste TOML in freier Wildbahn aus Wenn Sie einen gesehen haben Cargo.toml Mit mehreren [[bin]] Einträge, das haben Sie gesehen.

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

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

Der zweite ist ein Inline-tabelle Innerhalb eines normalen Arrays, das jedes Objekt auf einer Zeile packt.

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

Beide Hin - und Rückfahrt zu den gleichen Daten Welche Sie wollen, hängt vom Ziel und vom Geschmack ab Arrays von Tabellen lesen sich besser für Datensätze, die ein Mensch bearbeiten wird, und sie sind die Konvention für die meisten Tooling-Konfigurationen Inline-Tabellen sind kompakter und näher an der Form des ursprünglichen JSON, die manche Leute bevorzugen, wenn die Liste kurz ist oder die Objekte winzig sind Der Konverter setzt auf Arrays von Tabellen und gibt Ihnen einen Umschalter zum Umschalten Wenn Sie unsicher sind, lassen Sie es auf der Standardeinstellung: es ist, wie eine TOML-Datei normalerweise aussieht.

Was passiert mit JSON null in TOML?

TOML hat keine Null Es gibt kein Schlüsselwort, keinen leeren Wert, nichts. Dies ist eine bewusste Designentscheidung des Formats und der einzige Ort, an dem JSON zu TOML wirklich verlustbehaftet ist.

Der Konverter muss also eine Wahl treffen, und er lässt Sie es treffen Standardmäßig ein Schlüssel, dessen Wert ist null Wird fallen gelassen, und das Tool listet die fallengelassenen Tasten in einer Notiz unter der Ausgabe auf, so verschwindet nichts lautlos, wenn Sie die Taste lieber behalten möchten, können Sie auf das Schreiben von null als leere Zeichenfolge umsteigen, wodurch die Taste auf Kosten der Änderung ihres Typs erhalten bleibt Beides ist nicht perfekt, denn es gibt keine perfekte Antwort Entscheidend ist, dass die Wahl sichtbar und nicht vergraben ist.

Nullen innerhalb von Arrays werden immer weggelassen, mit einer Warnung, da ein TOML-Array überhaupt keine Null enthalten kann. Wenn Ihr JSON dies getan hat [1, null, 3]Das TOML wird sein [1, 3] Und das Tool wird Ihnen sagen, dass es eine entfernt hat. Wenn diese Nullen eine Bedeutung haben, ist das ein Signal, die Daten vor der Konvertierung und nicht danach neu zu formen.

Warum hat meine Zahl ihre Dezimalzahl verloren oder eine erhalten?

Dieser überrascht Menschen, denen Typen am Herzen liegen JSON unterscheidet nicht 5 aus 5.0. Beide analysieren das gleiche IEEE 754-Double und bis dahin JSON.parse Geschafft wird, fehlt jede Spur von der nachlaufenden Null. Wenn der Konverter also die Zahl sieht 5„Es gibt keine Möglichkeit zu wissen, dass Sie einen Schwimmer meinten, und seitdem 5 Ist eine ganze Zahl, schreibt sie eine TOML-Ganzzahl.

TOML hingegen unterscheidet ganze Zahlen von Floats, und einige Tools kümmern sich um den Unterschied. Wenn Sie einen als Float eingegebenen Wert benötigen, besteht der Fix darin, ihm einen Bruchteil in der Quelle zu geben, 5.1 oder 5.0 So geschrieben, dass es überlebt, oder um den einzelnen Wert nach der Konvertierung zu bearbeiten Es ist eine Änderung mit einem Zeichen und es ist selten, aber es lohnt sich zu wissen, warum es passiert, anstatt anzunehmen, dass der Konverter falsch ist Es ist nicht falsch JSON hat die Informationen einfach weggeworfen, bevor der Konverter sie jemals gesehen hat.

Der umgekehrte Fall wird mit sehr großen oder sehr kleinen Zahlen angezeigt, wobei JavaScript's String() Erzeugt Exponentenschreibweise wie 1e+21. TOML akzeptiert das als Float, also konvertiert es fein, aber die Form der Zahl kann anders aussehen als das, was Sie eingegeben haben Auch hier ist der Wert identisch; nur das Rendering hat sich geändert.

Wie funktionieren nackte und zitierte Schlüssel?

TOML lässt einen Schlüssel freischreiben, wenn er nur aus Buchstaben, Ziffern, Unterstrichen und Strichen besteht Alles andere, ein Schlüssel mit einem Punkt, ein Leerzeichen, ein Schrägstrich, ein Unicode-Zeichen, muss zitiert werden Der Konverter prüft jede Taste und zitiert nur diejenigen, die sie benötigen, also user-name Kahl bleibt und "user.name" Zitate bekommt, um zu verhindern, dass der Punkt als Tabellenpfad gelesen wird, darüber muss man nicht nachdenken, aber wenn man in der Ausgabe Zitate um eine Taste sieht, deshalb: die Taste enthielt ein Zeichen, das sonst seine Bedeutung ändern würde.

Ein gearbeitetes Beispiel

Hier ist das Beispiel, das das Werkzeug lädt, damit Sie jede Regel auf einmal sehen können. Der 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" }
  ]
}

Wird zu TOML, bei dem die Root-Skalare an erster Stelle stehen, die verschachtelten Objekte der Reihe nach zu gepunkteten Tabellen werden und das Serverarray aus zwei wird [[servers]] Blöcke:

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"

Beachten Sie, dass title, version und enabled Vor jeder Kopfzeile geschrieben werden roles Ein Inline-Array bleibt, da es sich um ein Array von Zeichenfolgen handelt, und [database.pool] Sitzt unter [database] Als gepunkteter Pfad Jede Regel in diesem Leitfaden ist in neun Ausgabereihen sichtbar.

Welches Tool für welche Konvertierung?

TOML ist ein Format in einer Familie, und das richtige Tool hängt davon ab, wo Sie beginnen und enden. So denke ich darüber.

Du hast	du willst	einsetzen
json	TOML-Konfiguration	JSON zu TOML
json	YAML-Konfiguration	json zu Yaml
Zank	json	YAML zu JSON
json	XML	JSON zu XML
Messy JSON	Lesbares JSON	JSON-Formater

Das Muster ist, dass Konfigurationsformate austauschbare Ansichten derselben Daten sind und der gewünschte Konverter nach der Richtung benannt ist, in die Sie gehen. TOML, YAML und JSON drücken alle verschachtelte Schlüssel-/Wertdaten aus; Der Unterschied besteht darin, welche Ihr Zielwerkzeug liest.

Ist es sicher, eine Config-Datei online zu konvertieren?

Config-Dateien sind genau die Art von Dingen, bei denen Sie vorsichtig sein sollten, wenn Sie sie in eine Website einfügen, da sie oft Verbindungszeichenfolgen, Token und andere Geheimnisse enthalten Die JSON-TOML-Konverter Läuft komplett in Ihrem Browser Das JSON, das Sie einfügen, wird im Speicher auf Ihrem Gerät analysiert, das TOML wird dort produziert, und nichts wird an einen Server gesendet, in ein Protokoll geschrieben oder gespeichert. Sie können sich das selbst ansehen: Öffnen Sie Ihren Netzwerk-Tab, führen Sie eine Konvertierung aus, und sehen Sie, dass keine Anfrage mehr ausgeht. Es funktioniert auch weiterhin ohne Verbindung, sobald die Seite geladen wurde, was der praktische Beweis dafür ist, dass die Arbeit lokal ist Wenn Sie sich darum kümmern, wohin Ihre Daten gehen, und bei einer Konfigurationsdatei sollten Sie das ist die Eigenschaft, auf die es ankommt. Es ist das gleiche Prinzip hinter jedem Tool auf der Website, und der Grund, warum ich ausführlich darüber in der Anmerkung geschrieben habe auf Datenschutz in Online-Toolsdrohen

Wo das in einen echten Workflow passt

Formatkonvertierung ist selten die ganze Aufgabe Es ist ein Schritt Man zieht ein Einstellungsobjekt aus einer API, man wandelt es um, man lässt es in ein Projekt fallen Der Wert eines clientseitigen Konverters ist, dass er reibungslos in diesen Fluss schlitzt: kein Upload, kein Account, kein Warten auf einem Server, keine Frage, ob sich deine Geheimnisse jetzt in jemandem befinden' s Logs. Das ist der gleiche Grund, warum ich das Ganze behalte Toolz.dev Setzen Sie die Client-Seite und es ist ein Thema, auf das ich im zurückkomme Entwicklerproduktivitätstools Schreiben Sie, denn die Tools, die Sie zwanzigmal am Tag erreichen, sind diejenigen, bei denen sich eine zweisekündige Hin- und Rückfahrt und eine Datenschutzfrage ergeben.

TOML hat sich seinen Platz in diesem Fluss verdient, indem es auf die beste Art und Weise langweilig ist Es analysiert überall das Gleiche, es liest sich gut, und seine eine scharfe Kante, die Bestellregel, ist genau das, was ein Konverter für Sie ablegen sollte Fügen Sie Ihren JSON ein, wählen Sie aus, wie Sie Arrays und Nullen handhaben möchten, und kopieren Sie TOML, das einfach funktioniert.

Häufig gestellte Fragen

Wie konvertiere ich JSON in TOML?

Fügen Sie Ihr JSON-Objekt in den Konverter ein und klicken Sie auf Konvertieren. Das Tool serialisiert Objekte in TOML-Tabellen, Arrays von Objekten in Arrays von Tabellen und jeden anderen Wert inline und gibt Ihnen dann Standard-TOML zum Kopieren. Das JSON der obersten Ebene muss ein Objekt sein, da ein TOML-Dokument immer eine Tabelle ist.

Wofür wird TOML angewendet?

TOML ist ein Konfigurationsdateiformat, das leicht lesbar und eindeutig zu analysieren ist Es ist das Konfigurationsformat für Rust' s Cargo (Cargo.toml), Python-Packaging (pyproject.toml), Hugo und viele Go - und Rust-Tools. Menschen konvertieren JSON in TOML, um eine maschinengenerierte Konfiguration an ein Tool zu übergeben, das TOML erwartet.

Was passiert mit JSON-Nullwerten in TOML?

TOML hat keinen Null-Typ, daher kann ein JSON null nicht direkt dargestellt werden. Standardmäßig lässt dieser Konverter Nullschlüssel fallen und fügt eine Notiz hinzu, in der sie aufgeführt sind; Sie können stattdessen dazu wechseln, sie als leere Zeichenfolgen zu schreiben. Nullen innerhalb von Arrays werden immer weggelassen, da ein TOML-Array keine Null enthalten kann.

Was ist der Unterschied zwischen einem Array von Tabellen und einer Inline-Tabelle?

Ein Array von Tabellen verwendet wiederholte Doppelklammern-Header, einen Block pro Datensatz, und ist die idiomatische TOML-Methode, um eine Liste von Objekten wie eine Liste von Servern oder Abhängigkeiten zu schreiben Eine Inline-Tabelle packt ein Objekt auf eine Zeile als Satz von Schlüssel gleich Wertpaaren in Klammern Dieses Tool ist standardmäßig für Arrays von Tabellen, aber können Sie wählen inline stattdessen.

Warum wurde aus meiner JSON-Nummer 5.0 5 in TOML?

JSON behält die Differenz zwischen 5 und 5.0 nicht bei, daher liest das Parsen beides als Zahl 5. Da 5 eine ganze Zahl ist, schreibt der Konverter sie als TOML-Ganzzahl, wenn Sie sie als Float eingeben müssen, fügen Sie einen Bruchteil in die Quelle ein oder bearbeiten Sie den einzelnen Wert nach der Konvertierung.

Behält der Konverter meine Schlüsselbestellung bei?

Ja. Schlüssel werden in der Reihenfolge ausgegeben, wie sie im JSON erscheinen, mit einer erforderlichen Neuanordnung: Innerhalb jeder Tabelle werden einfache Schlüssel vor beliebigen Untertabellen- oder Array-of-Tables-Headern geschrieben. Das ist eine TOML-Syntaxregel, keine Neuordnungsauswahl, und ohne sie würde die Datei nicht analysiert.

Wird mein JSON auf einen Server hochgeladen?

Nein. Die gesamte Konvertierung erfolgt in Ihrem Browser mit einfachem JavaScript. Ihr JSON, einschließlich aller Geheimnisse oder Anmeldeinformationen in einer Konfigurationsdatei, wird niemals übertragen, protokolliert oder gespeichert, und der Konverter arbeitet weiterhin ohne Verbindung, sobald die Seite geladen wurde.

Warum steht da, dass die oberste Ebene ein Objekt sein muss?

Ein TOML-Dokument ist als Tabelle definiert, das heißt, es muss von einem Satz Schlüssel/Wert-Paare ausgehen Ein blankes JSON-Array oder Skalar hat keine Tabelle, auf die abgebildet werden kann Wickeln Sie es zuerst in ein Objekt, legen Sie beispielsweise Ihr Array unter einen benannten Schlüssel, und es wird konvertieren.