YAML が初めて私をきちんと火傷したのは、国コードでした。 Laravel プロジェクトの JSON ファイルからロケール構成を展開しやすい YAML 形式に移動しました。これは、「ブレースをインデントに変更するだけです」という理由で、「ブレースをインデントに変更するだけ」でした。 "country": "NO"。 YAMLでは、引用符で囲まれていない、that& #39; sは文字列ではありません - YAML 1.1 ルールの下では、PyYAMLと他の多くのパーサーがまだ適用されます、 NO はブールです false。 Python で書かれたデプロイ スクリプトは、ノルウェーのユーザーを元気に評価しました。 country: false そしてそれらをフォールバックロケールにルーティングしました。このバグには名前があります - コミュニティはそれをノルウェー問題と呼んでいます - そして私はそれを職人技で発見することができました、一度に1枚ずつ混乱したサポートチケットです。
JSON を YAML に手動で変換することは、些細なことのように見え、実際には地雷原です。なぜなら、2 つの形式は、裸の言葉の意味について大きく異なる考え方を持っているからです。 JSON では、すべてが明示的です。文字列には引用符があり、数字にはありません。 true/false/null キーワード、ストーリーの終わりです。 YAML では、引用符で囲まれていないスカラーが取得されます 解釈された: no 偽りになり、 3000 整数になり、 1.10 フロートになります 1.1 (さようなら、バージョン文字列) 08 いくつかのパーサーを無効な 8 進数としてチョークし、迷走コロン空間を持つ値は、予想外の場合にネストされたマップになります。これらはすべてサイレント データ破損です。ファイルは正常に解析されますが、タイプは間違っているだけです。
あ JSON から YAML へのコンバータ これらのルールを理解することで、YAML は型ルーレットなしで発明された可読性が得られます。 Toolz.dev 用に構築したものは、すべてのあいまいなスカラー (ブール値類似、数値類似、YAML 1.1 レガシー値、特殊文字を含む文字列) を検出し、それらを正確に引用します。そのため、JSON の文字列は、次のツールが YAML を解析した後でも文字列になります。その "まさにそれらの "重要なことは引用です every 安全でも、出力は慣用的な YAML のように見えなくなり、Idiomatic が要点です。
このガイドでは、変換が YAML の鋭いエッジを処理する方法、技術的には JSON がすでに YAML である理由 (そして、なぜその事実が役に立たないのか)、およびこの変換が毎週行われる Kubernetes、CI、および Docker のワークフローについて説明します。
tl;dr: json に json を貼り Toolz.dev JSON から YAML へのコンバータ、2 スペースまたは4 スペースのインデントを選択し、型安全な引用符で囲まれたクリーンなブロックスタイルのYAMLを取得します -
"3000"文字列のまま、"no"文字列のまま、"1.10"バージョンのままです。 キーの順序は保持され、空のコレクションは次のように出力されます。[]あんど{}、すべてがクライアント側で実行されるため、秘密の設定はブラウザから離れることはありません。 で往復する YAML バリデータで、ソースを最初にフォーマットします。 JSON フォーマッタ。
JSON はすでに有効な YAML ではありませんか?
はい - そして、it& #39; s 最も役に立たない "yes" 設定管理で. YAML 1.2 は明示的に JSON のスーパーセットとして設計されました: すべての有効な JSON ドキュメントは有効な YAML として解析されます. kubernetes マニフェストに生の JSON を貼り付けることができます kubectl それを受け入れるでしょう。
YAML が存在する理由は、誰もこれを行いません。 人間工学。 Kubernetes マニフェスト、GitHub アクション ワークフロー、Docker Compose ファイル、Ansible プレイブック、Home Assistant コンフィグ - 人々が常に読み取って手作業で編集するため、これらは YAML です replicas: 3 インデントされたブロック スキャンは、よりも優れています。 {"replicas":3} 中かっこに入れ子。 誰かが「JSON を YAML に変換する」と言うとき、それは ブロックスタイル YAML: 中括弧の代わりにインデント。 - 括弧で囲まれた配列ではなく、ダッシュをダッシュします。必要のない引用符はありません。
その最後の条項は、困難が生きているところです。 JSON のすべての明示的な構文から YAML の最小限の構文に移行するという意味 文字列ごとに、引用符を安全に失う可能性があるかどうかを判断します- そしてその決定には、YAML's スカラー解像度のルールを知る必要があります。ほとんどの人間が金曜日の午後 5 時に確実に行うよりも優れています。それ's コンバーターの実際の仕事;中括弧からインデントまでの部分は簡単です。
手で変換すると、静かに何が壊れますか?
失敗のケースは 4 つのファミリに分類され、実際の構成ですべてのファミリに該当します。
ブールそっくりさん。 YAML 1.1 が解決する yes、 no、 on、 off、 y、 n (さまざまなケーシングで) Booleans として、YAML 1.2 は保持します true/false。 PyYAML - ほとんどの Python コードベースでは依然としてデフォルトの YAML ライブラリ - が 1.1 を実装します。それで "debug": "no" 手で変換 debug: no なる debug: false Python 展開ツールで。 ノルウェーの問題 (NO → false) とそのいとこオンタリオ問題 (ON → true) これは家族の最大のヒット曲ですか。
そっくりさんの数。 "port": "3000" に変換された port: 3000 は整数になりました。 Kubernetes does' いくつかのフィールドでは気にせず、他のフィールドではハードフェイルを行います - たとえば、env var 値は文字列である必要があります kubectl apply フィールドに名前を付けるエラーのある整数を拒否しますが、 なんでや。 バージョン文字列は、何も失敗しないため、さらに悪化します。 version: 1.10 フロートとして解析 1.1、そしてあなたのdeployスクリプトは喜んで永遠に間違ったバージョンを報告します。 leading zeros - postal codes, phone numbers, octal-looking IDs like 0755ー 家族を丸めろ.
特殊文字。 コロンの後に無引用の値の中にスペースが続くと、マッピング (message: error: not found パース エラーまたはネストされたマップ、パーサーに応じて)。 あ # コメントの中間値を開始します。 主要 *、 &、 ! YAML のアンカー、エイリアス、タグの構文で衝突します。 改行のある文字列は、スカラーをエスケープするかブロックする必要があります。
空の文字列。 YAML の引用符で囲まれた空の空は null、ない ""。 空の文字列を保持している JSON フィールドは、引用符で囲むか、タイプを変更する必要があります。
ザ・ コンバーター すべての文字列を 4 つのファミリーすべてに対してチェックし、必要なファミリーのみを引用します。 production あいまいであるため、むき出しになるからです。 "3000"、 "no"、 "1.10"、そして "" 彼らはそうではないので、引用して出てきます。 パーサーにフィードを与えている場合に備えて、「すべての文字列」をトグルして、信頼できず、スカラー解決をまったく必要としない場合に備えて、「すべての文字列」を切り替えることもできます。
ツールを使用して JSON を YAML に変換するにはどうすればよいですか?
ステップ 1: JSON を貼り付けます
有効なJSONはどれでも機能します - オブジェクト、配列、ディープネスト、 ユニコード。 「サンプル読み込み」ボタンを使用すると、興味深いケースを実行する現実的なサービス構成が得られます: 数値文字列ポート、ブール値、空の配列、ネストされたマップ。入力に構文上の問題がある場合、コンバータは切り詰められたドキュメントを変換するのではなく、parser' s の正確なエラーを報告します。ダウンハンティング用 どこ エラーは大きな塊にあり、 JSON フォーマッタ 顕微鏡の方が良いです。
ステップ 2: インデントを選択する
2 つのスペースまたは 4 つ。 2 つは圧倒的な規則です - Kubernetes ドキュメント、GitHub アクションの例、Docker Compose リファレンス、および yamllint デフォルトではすべてこれが使用されますが、一部のチームはディープ ネスティングでの読みやすさを考慮して 4 つを標準化しています。どちらを選択しても、コンバーターはそれについて一貫しています。これには、キーの下のリスト項目の微妙なケースも含まれます。一貫性のない手書きインデントは " の古典的なソースです。マッピング値はここでは許可されません。引用;エラー。
ステップ 3: 変換してレビューする
出力は行とバイト数で表示されます。 skim it once - not for correctness (that's the converter's job) but to sanity-check the quoting decisions against your expectations. (1 回スキムして、正確さ (that's the converter's job) ではなく、見積決定を見積りに対して正気度を確認します) PORT: "3000" 引用されたとき NODE_ENV: production どの値が危険であったかを伝えるツールです。
ステップ 4: コピーまたはダウンロード
クリップボードにコピーして既存のマニフェストに貼り付けるか、または .yaml ファイル。出力はスペースのみを使用します。YAML はインデント用のタブを禁止します。これは、後でタブのインデント用に構成されたエディタでファイルを編集するときに知っておく価値があります。
JSON と YAML: 各フォーマットはいつ勝ちますか?
| json | ヤムル | |
|---|---|---|
| によって読み上げられ、編集されました | マシン、API | 人間、作戦チーム |
| コメント | 仕様にはありません | # コメント - コンフィグのキラー機能 |
| タイプの明示性 | 合計 - 見積もりがすべてを決定します | スカラー解像度 - コンテキストが決定します |
| 複数行の文字列 | \n 脱出のみ |
ブロック スカラー (` |
| 解析速度とユビキタリ | どこでも、最速 | よりゆっくり、より重いパーサー |
| 足銃 | トレーリング・コンマ、それについて | ノルウェーの問題、タブ、インデント ドリフト、バージョンの切り捨て |
| 自然の生息地 | API ペイロード、 package.json、データ交換 |
Kubernetes、CI パイプライン、作成、Ansible |
表のパターン: JSON は、マシンが書き込み、マシンが読み取りを行う場合に勝ちます。YAML は、マシンが読み取りを行う場合はどこでも勝ちます。 人間 書き込みます。 構成は、2 番目のカテゴリに正方形に座って、これは、JSON-to-YAML方向が一般的なものである理由です - データはAPIまたはデータベースのエクスポートで寿命を開始し、opsチームが維持できるものになる必要がある逆のトリップ、YAMLバックマシン可読JSON、です YAML バリデータ ハンドル - YAML を貼り付け、検証と同等の JSON を取得します。
このコンバージョンの日常的なワークフローは何ですか?
API 出力からの Kubernetes マニフェスト
kubectl get deployment my-app -o json json; を与えます GitにチェックインしたマニフェストはYAMLです APIレスポンスをクリーンなYAMLに変換することは、ライブリソースからマニフェストをブートストラップする最速の方法です - 変換、サーバーが配置されたストリップ status あんど metadata.managedFields ブロックすると、宣言的な開始点があります。 タイプセーフの引用は、Kubernetes の env 値をここに保持します。 しなければな 文字列であり、コンバーターが引用することを主張する "3000" の違いです kubectl apply 成功と失敗。
CI パイプラインの構成
GitHub Actions と GitLab CI は YAML のみです。 I' m がワークフローのステップをプログラムで生成するとき - WP Adminify をテストするための PHP と Node バージョンの行列 たとえば - ジェネレータは自然に JSON を生成し、最後のステップは変換です。 test マトリックスのバージョン文字列は、まさにナイーブ変換によってめちゃくちゃになる値です: の行列です ["1.9", "1.10", "1.11"] 引用符なしで PHP に対するテストを手作業で変換する 1.1 二度。 ザ・ コーディング ツール コレクション この生成、変換パターンの詳細をカバーします。
Docker Composes から Inspect 出力から
docker inspect JSON を発行します。 docker-compose.yml YAML が欲しいです。 compose ファイルを実行中のコンテナー (ports, volumes, env) からリバースエンジニアリングすることは、変換とプルーンのジョブです。 空の配列とオブジェクトはに変換されます [] あんど {} 構成が受け入れ、剪定段階を読みやすく維持するフローの構文。
構成をレビュー可能にする
これは過小評価されています。数十個のネストされたキーを含む JSON 構成は、コメントを運べないため、コード レビューでは悲惨です。 YAML に変換すると、注釈を付けることができます なんでや rateLimit 値のすぐ隣にある 250 です。 レビュー自体の場合、変換を 構造差 JSON の前後の「何が実際に変わったか」の質問を正直に保ちますが、YAML バージョンは「なぜ」を処理します。
OpenAPI およびスキーマ ドキュメント
OpenAPI スペックは通常、YAML で作成されますが、生成され、JSON として提供されます。生成されたスペックを人間編集のために YAML に変換し、ラウンド トリップを検証することは、標準的な API チームのワークフローであり、忠実度の保証 (キー順序が保持され、型が引用される) により、YAML バージョンは JSON の祖先に対して差分性を維持します。
キーオーダーの保存が重要なのはなぜですか?
JSON 仕様によれば、オブジェクト キーの順序には意味がありません - {"a":1,"b":2} あんど {"b":2,"a":1} 同じオブジェクトです。 したがって、コンバータはキーをアルファベット順に並べ替え、技術的に正しいことができます。 構成ファイルは、 読んで 順番に: Kubernetes 展開は、次のように自然に読み取れます。 apiVersion、 kind、 metadata、 spec- これらをアルファベット順に並べると、同じように解析され、身代金メモのように読み取れるマニフェストが生成されます。
コンバータはソースの順序でキーを送信します。 ドキュメントのメンタル モデルは変換後も有効です。YAML は、以前の同じソースの変換と従来の順序 (値の前の名前、 apiVersion 第一) 従来のままである。 おったら 欲しい 比較を目的とした正規の順序付け、that' s の異なるツールに関する懸念 - JSON 差分チェッカー 順序に関係なく、キーで比較します。これは、その問題に適したレイヤーです。
秘密を含む設定を変換しても安全ですか?
設定は、開発者が処理する最も秘密密度の高いテキストです。埋め込まれたパスワードを含むデータベース URL、env ブロック内の API トークン、インフラストラクチャをマッピングする内部ホスト名。 It's は、人々がオンライン コンバーターに貼り付ける内容 (通常は導入中、通常は急いで) も正確に示します。
ザ・ Toolz.dev コンバータ 解析、スカラー分析、シリアル化など、完全にブラウザー内で実行されます。これらはすべてクライアント側の JavaScript であり、ネットワーク要求はデータを伝送せず、ツールは接続カットで動作し続けます。 That' s はアーキテクチャの事実であり、プライバシー ポリシーの約束ではありません。ツールボックス全体の背後にあるブラウザー優先の設計哲学は、 にレイアウトされています Web 開発者ツールキット ガイド; このツールは、ワークフローで最も機密性の高いドキュメント タイプに適用される哲学です。
明らかな注意点は、クライアント側の変換によって保護されます。 転向。 出力を後で貼り付けるのは、独自のセキュリティ上の決定です。
フェイク
JSON をオンラインで YAML に変換するにはどうすればよいですか?
JSON に貼り付けます。 JSON から YAML へのコンバータ、2 空間または4 空間インデントを選択し、変換をクリックします。 type-safe引用符で囲まれたブロックスタイルのYAMLを取得し、.yamlファイルとしてコピーまたはダウンロードする準備ができています。変換は完全にブラウザで実行されます。 - 何もアップロードされません。
JSON はすでに有効ですか?
技術的にははい - YAML 1.2 は JSON のスーパーセットであるため、有効な JSON ドキュメントは YAML として解析されます。しかし、JSON 構文は YAML's の可読性の目的を打ち破ります。変換すると、中括弧の代わりにインデントを含むブロック スタイルの YAML が生成されます。これは、Kubernetes がマニフェスト、CI ワークフロー、および Compose ファイルで、人間が読み取りおよび編集することを期待しています。
YAML のノルウェーの問題は何ですか?
PyYAML のようなパーサーが依然として適用される YAML 1.1 スカラー ルールでは、引用符で囲まれていない値 no、yes、on、off がブール値として解析されるため、国コード NO はサイレントに false になります。コンバーターは、YAML パーサーがブール値、数値、または null として解釈できる文字列を自動的に引用することで、これを防ぎます。
「3000」などの数値文字列は、変換後も文字列のままになりますか?
はい。 コンバータは、数字のように見える文字列を検出して出力で引用符を付けます。したがって、「3000」は整数 3000 になるのではなく、文字列のままです。 これは、ポート、「1.10」（そうでなければフロート 1.1 に切り捨てられる）、郵便番号、および先行ゼロの ID のようなバージョン番号に関係します。
コンバータは私の JSON キーの順序を保持しますか?
はい。 キーはソース JSON に表示される順序で発行されます。キーの並べ替えは技術的に有効です。JSON オブジェクトの順序には意味がありません RFC 8259- ただし、ソース順序は従来の構造でコンフィグを読み取り可能に保ち、YAML を JSON ソースに対して差分可能に保ちます。
出力を Kubernetes または Docker Compose で直接使用できますか?
はい。出力は、スペース (タブなし) でインデントされた標準のブロック スタイルの YAML であり、kubectl、Docker Compose、GitHub Actions、および GitLab CI はすべてこれを受け入れます。 kubernetes env var 値のように、文字列でなければならない値は引用符で囲まれて表示され、引用符で囲まれていない数値に対して kubectl が発生させる型エラーを回避します。
YAML を JSON に戻すにはどうすればよいですか?
を使用する YAML バリデータ on Toolz.dev - yaml を解析し、構文エラーを報告し、同等の JSON を出力します。 JSON to YAML Converter と合わせて、2 つの形式間の完全な往復が得られます。
シークレットを含む構成ファイルを変換しても安全ですか?
はい。変換はブラウザの JavaScript で完全に実行されます。ネットワーク リクエストではデータが伝送されず、何も保存またはログに記録されず、ツールはオフラインで動作します。データベースの資格情報、API トークン、または内部ホスト名を含む構成はマシンから離れることはありません。
YAML& #39; sの可読性は本物であり、その鋭いエッジも同様です - フォーマットはコンテキストから型を解決し、コンテキストはまさにハンドコンバージョンが間違っているものです スカラールールを知っているコンバーターは、サイレントタイプの破損なしに読み取り可能な構成を提供します: JSON を変換する、それが選んだ引用をすくい取って、ノルウェーがまだ国であるところにマニフェストを出荷します。
