YAMLとJSONの変換で起きる落とし穴|先頭の0、yes/no、日付、コメント
この記事の要点
- YAML は、書き方によって、値の型が変わります。
01234は数値の 1234 になり、先頭の 0 が消えます。2026-11-17は、日付として読まれることがあります。 yes・no・NOは、読み込むツールによって、文字列にも真偽値にもなります。同じ YAML でも、結果が違います。- YAML から JSON に変換すると、コメントは消えます。JSON に戻しても、元には戻りません。
- 迷う値は、引用符(
")で囲むと、どのツールでも文字列として読まれます。
1. 値の型が変わる
JSON では、文字列は必ず " で囲みます。YAML では、囲まなくても書けるため、書かれた中身から、読み込む側が型を推測します。そのため、文字列のつもりで書いた値が、数値になることがあります。YAML→JSON変換ツールで、次の YAML を変換した結果です。
| YAML の書き方 | JSON になった結果 | 起きたこと |
|---|---|---|
zip: 01234 | 1234(数値) | 先頭の 0 が消える |
ver: 1.10 | 1.1(数値) | 末尾の 0 が消える(1.10 と 1.1 が区別できない) |
ver2: 1.0 | 1(数値) | 小数点以下が消える |
port: 8080 | 8080(数値) | 数値として読まれる |
port: "8080" | "8080"(文字列) | 引用符で囲むと、文字列のまま |
hex: 0x1F | 31(数値) | 16進数として読まれる |
oct: 0o17 | 15(数値) | 8進数として読まれる |
郵便番号、電話番号、バージョン番号、商品コードのように、数字だけで書くが、数値ではない値は、必ず引用符で囲みます。zip: "01234"、ver: "1.10" と書くと、ツールの結果は "01234"、"1.10" の文字列になります(確かめました)。
空の値と ~、null は、どれも JSON の null になります。空の文字列にしたいときは、"" と書きます。
2. yes・no・NO の扱いが、ツールで違う
YAML には、1.1 と 1.2 という、規則のバージョンがあります。yes・no・on・off を真偽値として読むのは、古い 1.1 の規則です。1.2 では、true と false だけが真偽値です。同じ YAML を、2つのツールで読んだ結果です。
| YAML の書き方 | YAML→JSON変換ツール (js-yaml 4.1.0、1.2) | PyYAML 6.0.3 (1.1) |
|---|---|---|
a: yes | "yes"(文字列) | true |
b: no | "no"(文字列) | false |
c: on | "on"(文字列) | true |
d: off | "off"(文字列) | false |
f: NO | "NO"(文字列) | false |
g: Y | "Y"(文字列) | "Y"(文字列) |
よく知られた失敗が、NO です。国コードの一覧に、ノルウェー(NO)を書くと、1.1 の規則のツールでは、false になってしまいます。これは「ノルウェー問題」と呼ばれます。
つまり、ブラウザのツールで確認した結果が、本番で読み込むプログラムの結果と同じとは、限りません。設定ファイルを読み込む側のライブラリが、1.1 か 1.2 かは、ライブラリごとに違います。この記事では、js-yaml 4.1.0 と PyYAML 6.0.3 以外は、確認していません。
対処は単純で、yes、no、on、off、NO のような値を文字列として使うときは、引用符で囲みます。真偽値として使うときは、true と false と書きます。この2つは、どちらの規則でも同じ意味です。"NO"、"yes" と書いた場合、PyYAML でも文字列として読まれることを、確かめました。
3. 日付と時刻
YAML→JSON変換ツールで、日付や時刻に見える値を変換しました。
| YAML の書き方 | YAML→JSON変換ツールの結果 |
|---|---|
date: 2026-11-17 | "2026-11-17T00:00:00.000Z" |
ts: 2026-11-17 09:30:00 | "2026-11-17T09:30:00.000Z" |
time: 12:30 | "12:30"(文字列のまま) |
date: "2026-11-17" | "2026-11-17"(文字列のまま) |
日付だけを書いたつもりが、時刻(00:00:00)とタイムゾーン(Z、UTC)が付いた文字列に変わります。タイムゾーンを書かなかった時刻(09:30:00)も、UTC として扱われました。日本時間で書いた時刻が、9時間ずれて解釈される原因になります。日付を、2026-11-17 のまま使いたいときは、引用符で囲みます。
12:30 は、js-yaml 4.1.0 では文字列でした。一方、YAML 1.1 の PyYAML 6.0.3 では、12:30 が数値の 750(60進数として、12×60+30)になりました。zip: 01234 も、8進数と見なされ、668 になりました。時刻も、引用符で囲んでおくと、安全です。
4. 変換で失われるもの
コメント
JSON には、コメントがありません。YAML→JSON変換ツールで、次の YAML を変換すると、コメントは出力に残りません。
# 接続先
host: example.com # 本番
port: 443
結果は {"host": "example.com", "port": 443} だけです。この JSON を YAML に戻しても、コメントは戻りません。コメントの付いた設定ファイルを、JSON で往復させて保存すると、説明が消えます。変換結果は、確認用に使い、元の YAML ファイルを残してください。
アンカーとエイリアス
YAML では、&名前 で値に名前を付け、*名前 で再利用できます。<<: *名前 は、内容を取り込んで、一部を上書きします。変換ツールでは、次のように、すべて展開された形になりました。
base: &b
host: localhost
port: 5432
dev:
<<: *b
port: 5433
prod: *b
結果は、dev が {"host": "localhost", "port": 5433}、prod が {"host": "localhost", "port": 5432} です。展開された JSON を YAML に戻しても、共通部分は元のアンカーには、戻りません。同じ内容が、そのまま繰り返し書かれます。
複数行の文字列
|(改行を残す)と >(改行を空白に折りたたむ)は、結果が違います。ツールの結果は、| が "1行目\n2行目\n"、> が "1行目 2行目\n" でした。> では、行の区切りが、空白に変わります。
5. JSON から YAML にするとき
逆向きでは、文字列に見えない文字列を、ツールが自動で引用符で囲みます。JSON→YAMLの変換結果です。
| JSON の値 | YAML の結果 |
|---|---|
"true" | 'true' |
"123" | '123' |
"yes" | 'yes' |
"01234" | '01234' |
"2026-11-17" | '2026-11-17' |
"null" | 'null' |
"a: b" | 'a: b' |
""(空文字列) | '' |
文字列のまま、型が変わらないように、引用符が付きます。
次の点にも、注意してください。
- 大きな数値は、丸められます。JSON の
12345678901234567890は、YAML では12345678901234567000になりました。ブラウザの JavaScript は、数値を 64bit の浮動小数点数で扱うため、約 15〜17 桁より先の精度がありません。ID のように、桁数の多い数値は、JSON の段階で、文字列("12345678901234567890")にしておきます。 - キー名にも、引用符が付く場合があります。
"n"というキーは、YAML では'n': ~と出力されました。値のnullは、~と出力されます。キー名を使う側で、読み込み結果を確認してください。 - インデント幅は変えられません。YAML→JSON の出力は、2スペースで固定です。
6. エラーになる書き方
YAML→JSON変換ツールで、エラーになった書き方です。エラーの文章は、ライブラリが出すもので、英語です。
| 書き方 | エラーの内容(ツールの表示) | 直し方 |
|---|---|---|
| インデントにタブを使った | tab characters must not be used in indentation | スペースに直す |
| 同じキーを2回書いた | duplicated mapping key | どちらかを消す |
値の中に : (コロンと空白)があるmsg: hello: world | bad indentation of a mapping entry | msg: "hello: world" のように、引用符で囲む |
--- で、複数のドキュメントを書いた | expected a single document in the stream, but found more | 1つずつ、別々に変換する |
なお、url: http://example.com:8080/a のように、コロンの後ろに空白がなければ、エラーにはならず、文字列として読まれます(ツールで確認しました)。
JSON→YAML のときは、JSON の側のエラーです。コメント(//)と、末尾のカンマ({"a":1,})は、JSON として正しくないため、エラーになります。どちらも、ブラウザの JSON 読み込みが、位置つきのエラーを出しました。
確認していないこと: Go、Ruby、Java など、js-yaml と PyYAML 以外のライブラリでの結果は、確認していません。使っているライブラリの規則(1.1 か 1.2 か)は、そのライブラリの説明で、確認してください。迷う値を引用符で囲む対処は、確かめた2つのライブラリで、有効でした。
7. よくある質問
- YAML と JSON は、どちらを使うべきですか?
- 人が読み書きする設定ファイルには、コメントが書ける YAML が向きます。プログラム同士のやり取り(API など)では、規則が単純で、読み込み結果がぶれにくい JSON が向きます。この記事で見たとおり、YAML は、書き方で型が変わるため、手で書く値が増えるほど、引用符の判断が必要です。
- すべての文字列に、引用符を付けておけば安全ですか?
- 型の誤認は防げます。ただし、読みにくくなります。数字だけの値、日付や時刻に見える値、
yes・noに見える値、:や#を含む値だけを、囲むのが現実的です。 - JSON の方が、YAML のサブセット(一部分)だと聞きました。
- YAML 1.2 は、JSON を含む形で作られています。ただし、ライブラリの実装で、細かい違いが出る可能性があるので、この記事では、確認していません。
- 変換した内容は、サーバーに送られますか?
- 送られません。変換は、ブラウザの中だけで行います。変換に使うライブラリ(js-yaml)は、最初に CDN(cdn.jsdelivr.net)から読み込みますが、入力した内容は送りません。