Das erste Mal, dass YAML mich richtig verbrannte, war es ein Ländercode. Ich habe eine Gebietsschemakonfiguration aus einem Laravel-Projekt in ein deploymentfreundliches YAML-Format verschoben, das von Hand umgewandelt wurde, weil "es nur die Klammern in die Einrückung umwandelt." Einer der Einträge war Norwegen: "country": "NO". In YAML, nicht zitiert, dass & #39; s keine Zeichenfolge - unter den YAML 1.1-Regeln, die PyYAML und viele andere Parser noch anwenden, NO ist der Boolesche falsedrohen Das in Python geschriebene Deploy-Skript, das norwegische Benutzer fröhlich als country: false und leitete sie zum Fallback-Standort weiter Dieser Fehler hat einen Namen - die Community nennt es Norwegen-Problem - und ich durfte ihn auf handwerkliche Weise entdecken, ein verwirrtes Support-Ticket nach dem anderen.
Das Hand-Konvertieren von JSON in YAML sieht trivial aus und ist eigentlich ein Minenfeld, da die beiden Formate sehr unterschiedliche Vorstellungen darüber haben, was ein bloßes Wort bedeutet. In JSON ist alles explizit: Zeichenfolgen haben Anführungszeichen, Zahlen nicht, true/false/null sind Schlüsselwörter, Ende der Geschichte. In YAML wird ein nicht zitierter Skalar gedeutet: no wird falsch, 3000 wird eine ganze Zahl, 1.10 wird der Schwimmer 1.1 (Auf Wiedersehen, Versionszeichenfolge), 08 Würgt einige Parser als ungültiges Oktal ab, und ein Wert mit einem verirrten Doppelpunkt wird zu einer verschachtelten Karte, wenn Sie es am wenigsten erwarten. Jede davon ist eine stille Datenbeschädigung - die Datei analysiert gut, die Typen sind einfach falsch.
ein JSON-zu-YAML-Konverter Das versteht diese Regeln bringt Ihnen die Lesbarkeit, für die YAML ohne den Typ Roulette erfunden wurde. Der, den ich für Toolz.dev erstellt habe, erkennt jeden mehrdeutigen Skalar - boolesche Look-Alikes, Zahlen-Look-Alikes, YAML 1.1 Legacy-Werte, Zeichenfolgen mit Sonderzeichen - und zitiert genau diese, also ist das, was ein String in Ihrem JSON war, immer noch ein String, nachdem das nächste Tool das YAML analysiert hat. Dass & quot; genau das" zählt: zitieren alles wäre auch sicher, aber der Ausgang sieht nicht mehr wie idiomatisches YAML aus, und idiomatisch ist der springende Punkt.
In diesem Handbuch wird beschrieben, wie die Konvertierung mit den scharfen Kanten von Yaml umgeht, warum JSON technisch bereits YAML ist (und warum Ihnen diese Tatsache nicht hilft), und die Kubernetes, CI und Docker-Workflows, in denen diese Konvertierung wöchentlich erfolgt.
tl; dr: Fügen Sie JSON in die Toolz.dev JSON zu YAML-KonverterWählen Sie 2 - oder 4-Leerzeichen-Einrückung aus und erhalten Sie sauberes YAML im Blockstil mit typsicheren Anführungszeichen -
"3000"bleibt eine Schnur,"no"bleibt eine Schnur,"1.10"Bleibt eine Version. Die Schlüsselreihenfolge bleibt erhalten, leere Sammlungen kommen als heraus[]und{}, und alles läuft clientseitig, so dass Konfigurationen mit Geheimnissen niemals Ihren Browser verlassen. Rückfahrt mit dem YAML-Validator, und formatieren Sie zuerst die Quelle mit dem JSON-Formaterdrohen
Ist JSON nicht bereits gültig?
Ja - und es' s das nutzloseste & quot; yes" in der Konfigurationsverwaltung YAML 1.2 wurde explizit als eine Obermenge von JSON konzipiert: jedes gültige JSON-Dokument analysiert als gültiges YAML. Sie könnten rohes JSON in ein Kubernetes-Manifest einfügen und kubectl würde es akzeptieren.
Niemand tut dies, denn der Grund, warum YAML existiert menschliche Ergonomie. Kubernetes-Manifests, GitHub-Aktionen-Workflows, Docker Compose-Dateien, Ansible-Playbooks, Home Assistant-Konfigurationen - das sind YAML, weil die Leute sie ständig lesen und von Hand bearbeiten, und replicas: 3 Unter einem eingerückten Block scannt besser als {"replicas":3} in Zahnspangen eingebettet. Wenn jemand "JSON in YAML umwandeln" sagt, meinen Blockstil YAML: Einbuchtung statt Zahnspange, - Striche anstelle von Arrays in Klammern, keine Anführungszeichen, bei denen keine benötigt werden.
In dieser letzten Klausel lebt die Schwierigkeit. Von JSONs Everything-Explicit-Syntax zu Yams minimaler Syntax bedeutet Entscheiden Sie für jede Zeichenfolge, ob sie ihre Anführungszeichen sicher verlieren kann- und diese Entscheidung erfordert, dass man YAML's Skalarauflösungsregeln besser kennt, als die meisten Menschen es zuverlässig bei 5 PM an einem Freitag tun. That's die eigentliche Aufgabe eines Konverters; Der Teil von der Zahnspange zur Einrückung ist trivial.
Was bricht still, wenn Sie von Hand umwandeln?
Die Fehlerfälle fallen in vier Familien, und ich habe jeden von ihnen in echten Konfigurationen getroffen:
Boolesche Look-Alikes. YAML 1.1 wird behoben yes, no, on, off, y, n (in verschiedenen Gehäusen) als Boolesche und YAML 1.2 true/false. PyYAML - immer noch die Standard-YAML-Bibliothek in den meisten Python-Codebasen - implementiert 1.1. Also "debug": "no" handverstellt zu debug: no wird debug: false in Ihrem Python-Bereitstellungstool. Das Norwegen-Problem (NO → false) und sein Cousin das Ontario-Problem (ON → true) sind die größten Hits dieser Familie.
Nummern-Alikes. "port": "3000" umgerechnet auf port: 3000 Ist jetzt eine ganze Zahl. Kubernetes tut & #39; In einigen Bereichen ist es egal und in anderen ist es schwierig, Fehler zu machen - env var-Werte müssen beispielsweise Zeichenfolgen sein und kubectl apply wird dort eine Ganzzahl mit einem Fehler ablehnen, der das Feld benennt, aber nicht die wiesodrohen Versionszeichenfolgen sind schlimmer, weil nichts fehlschlägt: version: 1.10 Analysiert als der Float 1.1‘und Ihr Deploy-Skript meldet glücklich für immer die falsche Version Führende Nullen - Postleitzahlen, Telefonnummern, oktal aussehende IDs wie 0755- die Familie abrunden.
Sonderzeichen. Ein Doppelpunkt, gefolgt von einem Leerzeichen in einem nicht zitierten Wert, startet eine Zuordnung (message: error: not found ist ein Parse-Fehler oder eine verschachtelte Karte, Parser abhängig). ein # Startet einen Kommentar mittiger Wert. führend *, &, ! kollidieren Sie mit Yams Anchor, Alias und Tag-Syntax. Zeichenfolgen mit Newlines müssen entkommen oder blockiert werden.
die leere Zeichenfolge. Nicht zitierte Leere in YAML ist null, nicht ""drohen Jedes JSON-Feld, das eine leere Zeichenfolge enthält, muss zitiert herauskommen oder es ändert sich den Typ.
der Konverter Prüft jede Zeichenfolge gegen alle vier Familien und zitiert diejenigen, die sie brauchen - und nur diese. production kommt kahl heraus, weil es eindeutig ist; "3000", "no", "1.10", und "" Kommen Sie zitiert, weil sie es nicht sind. Es gibt auch ein "Zitat Alle Zeichenfolgen" umzuschalten, wenn Sie einen Parser füttern, dem Sie nicht vertrauen und der überhaupt keine skalare Auflösung finden soll.
Wie konvertiert man JSON mit dem Tool in YAML?
Schritt 1: Füge deinen JSON ein
Alle gültigen JSON-Funktionen - Objekte, Arrays, tiefe Verschachtelung, unicode. Die Schaltfläche Beispiel laden gibt Ihnen eine realistische Service-Konfiguration, die die interessanten Fälle ausübt: ein numerischer String-Port, ein boolescher, ein leeres Array, verschachtelte Karten Wenn Ihre Eingabe Syntaxprobleme hat, meldet der Konverter den Parser' s exakten Fehler, anstatt ein verkürztes Dokument zu konvertieren; zum Herunterjagen wohin Der Fehler ist in einem großen Blob, der JSON-Formater ist das bessere Mikroskop.
Schritt 2: Einzug wählen
Zwei Leerzeichen oder vier. Zwei ist die überwältigende Konvention - Kubernetes-Dokumente, GitHub-Aktionen-Beispiele, Docker Compose-Referenzen und die yamllint Standardmäßig wird es alle verwendet - aber einige Teams standardisieren auf vier für die Lesbarkeit in Deep Nesting, was auch immer Sie auswählen, der Konverter ist darin konsistent, einschließlich des subtilen Falles von Listenelementen unter einem Schlüssel, bei dem inkonsistente Handeinrückung eine klassische Quelle für & quot; Zuordnungswerte ist hier nicht erlaubt" Fehler.
Schritt 3: Konvertieren und überprüfen
Die Ausgabe erscheint mit Zeilen - und Bytezählungen Überfliegen Sie sie einmal - nicht wegen der Korrektheit (das' s der Konverter' s-Job) sondern um die Sauberkeit zu überprüfen - überprüfen Sie die Zitatentscheidungen gegen Ihre Erwartungen Sehen PORT: "3000" Während zitiert NODE_ENV: production ist das Werkzeug, das Ihnen sagt, welche Werte gefährlich waren.
Schritt 4: Kopieren oder herunterladen
In die Zwischenablage zum Einfügen in ein vorhandenes Manifest kopieren oder als Download als .yaml Datei. Die Ausgabe verwendet nur Leerzeichen - YAML verbietet Tabulatoren für die Einrückung, was es wert ist, wenn Sie die Datei später in einem für die Tabulatoreinrückung konfigurierten Editor bearbeiten.
JSON vs YAML: Wann gewinnt jedes Format?
| json | Zank | |
|---|---|---|
| gelesen / bearbeitet von | Maschinen, APIs | Menschen, Ops-Teams |
| Kommentar | Nicht in der Spezifikation | # Kommentare - die Killerfunktion für Configs |
| Typ Explizitität | Total - Zitate entscheiden alles | Skalarauflösung - Kontext entscheidet |
| Mehrzeilige Zeichenfolgen | \n entkommt nur |
Blockskalare (` |
| Parse Speed & Ampere | Am schnellsten, überall | langsamere, schwerere Parser |
| Fußwerk | Nachkomma, das ist es | Norwegen Problem, Tabs, Einzugsdrift, Versionsabbrüche |
| Natürlicher Lebensraum | API-Nutzlasten, package.json, Datenaustausch |
Kubernetes, CI-Pipelines, komponieren, Ansible |
Das Muster hinter der Tabelle: JSON gewinnt, wo immer eine Maschine schreibt und eine Maschine liest, YAML gewinnt, wo immer eine Maschine liest, aber a Mensch Schreibt Konfiguration sitzt eckig in der zweiten Kategorie, weshalb die JSON-zu-YAML-Richtung die übliche ist - Daten starten Leben in einer API oder einem Datenbank-Export und müssen etwas werden, was ein ops-Team pflegen kann Der Reverse Trip, YAML zurück zu maschinenlesbarem JSON, ist das, was die YAML-Validator Griffe - fügen Sie YAML ein, erhalten Sie eine Validierung plus das entsprechende JSON.
Was sind die alltäglichen Workflows für diese Konvertierung?
Kubernetes-Manifeste aus der API-Ausgabe
kubectl get deployment my-app -o json Gibt Ihnen JSON; das Manifest, das Sie in Git überprüfen, ist YAML. Die Umwandlung von API-Antworten in sauberes YAML ist die schnellste Möglichkeit, ein Manifest von einer Live-Ressource zu booten - konvertieren, den Server strippen status und metadata.managedFields blockiert, und Sie haben einen deklarativen Ausgangspunkt. Das typsichere Zitat verdient hier seinen Weg: ENV-Werte in Kubernetes müssen Seien Sie Strings und der Konverter besteht darauf, zu zitieren "3000" ist der Unterschied zwischen kubectl apply Erfolg und scheitern.
CI-Pipeline-
GitHub Actions und GitLab CI sind YAML-only Wenn I' m Workflow-Schritte programmgesteuert generiert - eine Matrix aus PHP - und Node-Versionen zum Testen von WP Adminify gegen, sagen wir - der Generator erzeugt natürlich JSON, und der letzte Schritt ist die Konvertierung Versionszeichenfolgen in Testmatrizen sind genau die Werte, die durch naive Konvertierung verstümmelt werden: eine Matrix aus ["1.9", "1.10", "1.11"] Hand-umgewandelt ohne Anführungstests gegen PHP 1.1 zweimal der Sammlung von Codierungstools Deckt mehr von diesem Generierung-Dann-Konvertierungsmuster ab.
Docker Componieren von Inspect Output
docker inspect emittiert JSON; docker-compose.yml YAML will. Reverse-Engineering einer Compose-Datei aus einem laufenden Container - Ports, Volumes, env - ist ein Convert-and-Prune-Job Leere Arrays und Objekte konvertieren in [] und {} Flow-Syntax, die akzeptiert und die Schnittphase lesbar hält.
Konfiguration überprüfbar machen
Dieser wird unterschätzt: JSON-Konfigurationen mit Dutzenden verschachtelten Schlüsseln sind bei der Code-Überprüfung miserabel, auch weil sie keine Kommentare übertragen können. Konvertierung in YAML ermöglicht es Ihnen, Anmerkungen zu machen wieso rateLimit ist 250 direkt neben dem Wert. Für die Überprüfung selbst, Paaren der Konvertierung mit a Strukturunterschied von vor / nach JSON hält die "Was tatsächlich geändert" -Frage ehrlich, während die YAML-Version das "Warum" behandelt.
OpenAPI- und Schemadokumente
OpenAPI-Spezifikationen werden üblicherweise in YAML verfasst, aber generiert und als JSON verwendet. Die Konvertierung einer generierten Spezifikation in YAML für die menschliche Bearbeitung - und die anschließende Validierung des Round-Trips - ist ein Standard-API-Team-Workflow, und die Treuegarantien (Schlüsselreihenfolge erhalten, Typen zitiert) bedeuten, dass die YAML-Version gegenüber ihrem JSON-Vorfahren diffundierbar bleibt.
Warum ist die Erhaltung der Schlüsselauftragserscheinungen wichtig?
Gemäß der JSON-Spezifikation hat die Reihenfolge der Objektschlüssel keine Bedeutung - {"a":1,"b":2} und {"b":2,"a":1} sind das gleiche Objekt. Ein Konverter könnte also die Tasten alphabetisch sortieren und technisch korrekt sein. Es wäre auch praktisch feindselig, weil Konfigurationsdateien lesen In der Reihenfolge: Eine Kubernetes-Bereitstellung liest sich natürlich als apiVersion, kind, metadata, spec- Das alphabetische Sortieren dieser Elemente führt zu einem Manifest, das identisch analysiert und sich wie eine Lösegeldnote liest.
Der Konverter gibt Schlüssel in der Quellenreihenfolge aus. Ihr mentales Modell des Dokuments überlebt die Konvertierung, der YAML unterscheidet sich sauber von früheren Konvertierungen derselben Quelle und konventioneller Reihenfolge (Name vor Wert, apiVersion Ersten) bleiben konventionell. Wenn du Bedürf Kanonische Reihenfolge zu Vergleichszwecken, die & #39;s ein Diff-Tool-Anliegen - das JSON Diff Checker Vergleicht nach Schlüssel unabhängig von der Reihenfolge, was die richtige Ebene für dieses Problem ist.
Ist es sicher, Konfigurationen mit Geheimnissen zu konvertieren?
Konfiguration ist der geheimste Text, den ein Entwickler verarbeitet - Datenbank-URLs mit eingebetteten Passwörtern, API-Token in env-Blöcken, interne Hostnamen, die Ihre Infrastruktur abbilden It's auch genau das, was Menschen in Online-Konverter einfügen, normalerweise in der Mitte der Bereitstellung, normalerweise in Eile.
der Toolz.dev-Konverter Läuft vollständig in Ihrem Browser: Parsen, Skalaranalyse, Serialisierung - alles ist clientseitiges JavaScript, keine Netzwerkanfrage trägt Ihre Daten und das Tool arbeitet mit Ihrem Verbindungsschnitt weiter. That's ist eine Architekturfakt, kein Versprechen der Datenschutzpolitik Die Browser-First-Designphilosophie hinter der gesamten Toolbox ist in der enthalten Leitfaden für Webentwickler-Toolkit; Dieses Tool ist die Philosophie, die auf den sensiblesten Dokumenttyp in Ihrem Workflow angewendet wird.
Die offensichtliche Einschränkung steht: Clientseitige Umwandlung schützt die Umwandlungdrohen Wo Sie die Ausgabe danach einfügen, ist ihre eigene Sicherheitsentscheidung.
FAQ
Wie konvertiere ich JSON online in YAML?
Fügen Sie Ihren JSON in die ein JSON-zu-YAML-Konverter2 - oder 4-Leerzeichen-Einrückung wählen, und auf Konvertieren klicken Sie Sie Sie erhalten block-Stil YAML mit typsicherem Zitat, bereit zum Kopieren oder Herunterladen als .yaml-Datei Die Konvertierung läuft vollständig in Ihrem Browser - es wird nichts hochgeladen.
Ist JSON bereits gültig YAML?
Technisch ja - YAML 1.2 ist eine Obermenge von JSON, daher analysiert jedes gültige JSON-Dokument als YAML. Aber die JSON-Syntax besiegt YAML's-Lesbarkeitszweck. Durch Konvertieren entsteht YAML im Blockstil mit Einrückung anstelle von Klammern, was Kubernetes manifestiert, CI-Workflows und Compose-Dateien erwarten, dass Menschen lesen und bearbeiten.
Was ist das Norwegen-Problem in YAML?
Unter YAML 1.1 Skalarregeln, die Parser wie PyYAML weiterhin anwenden, werden die nicht zitierten Werte nein, ja, ein und aus dem Parse als boolesch - der Ländercode NO wird also stillschweigend falsch Der Konverter verhindert dies, indem er automatisch jede Zeichenfolge zitiert, die ein YAML-Parser als boolesch, Zahl oder Null interpretieren könnte.
Bleiben numerische Zeichenfolgen wie "3000" nach der Konvertierung strings?
Ja. Der Konverter erkennt Strings, die wie Zahlen aussehen, und zitiert sie in der Ausgabe, so dass "3000" eine Zeichenfolge bleibt, anstatt die ganze Zahl 3000 zu werden. Dies ist wichtig für Ports, Versionsnummern wie "1.10" (die sonst an den Float 1.1 abschneiden würden), Postleitzahlen und IDs mit führenden Nullen.
Behält der Konverter die Reihenfolge meiner JSON-Schlüssel bei?
Ja. Schlüssel werden in der Reihenfolge ausgegeben, in der sie im Quell-JSON erscheinen. Sortierschlüssel wären technisch gültig - JSON-Objektreihenfolge hat keine Bedeutung pro RFC 8259- aber die Quellreihenfolge hält Konfigurationen in ihrer herkömmlichen Struktur lesbar und hält die YAML an ihrer JSON-Quelle diffundierbar.
Kann ich die Ausgabe direkt in Kubernetes oder Docker Compose verwenden?
Ja. Die Ausgabe ist standardmäßig im Blockstil YAML mit Leerzeichen (never tabs) eingerückt, die kubectl, Docker Compose, GitHub Actions und GitLab CI alle akzeptieren Werte, die Zeichenfolgen sein müssen - wie Kubernetes env var-Werte - kommen zitiert heraus, wodurch die Typfehler vermieden werden, die kubectl auf nicht zitierten Numeriken erhöht.
Wie konvertiere ich YAML zurück in JSON?
Verwenden Sie die YAML-Validator Auf Toolz.dev - es analysiert Ihre YAML, meldet alle Syntaxfehler und gibt den entsprechenden JSON aus. Zusammen mit dem JSON-YAML-Konverter erhalten Sie eine vollständige Hin- und Rückfahrt zwischen den beiden Formaten.
Ist es sicher, Konfigurationsdateien zu konvertieren, die Geheimnisse enthalten?
Ja. Die Konvertierung läuft komplett in JavaScript in Ihrem Browser - keine Netzwerkanfrage trägt Ihre Daten, nichts wird gespeichert oder protokolliert, und das Tool funktioniert offline. Konfigurationen mit Datenbankanmeldeinformationen, API-Token oder internen Hostnamen verlassen Ihren Computer nie.
YAML' s Lesbarkeit ist real, und so sind auch seine scharfen Kanten - das Format löst Typen aus dem Kontext, und Kontext ist genau das, was Hand-Konvertierung falsch wird Ein Konverter, der die skalaren Regeln kennt, gibt Ihnen die lesbare Konfiguration ohne die stille Typ-Beschädigung: Konvertieren Sie Ihren JSON, überfliegen Sie die von ihm gewählten Zitate und versenden Sie ein Manifest, in dem Norwegen noch ein Land ist.
