AWS のドキュメントや設定例を開くと、波かっこだらけの塊や、字下げだけで並んだ行に出会います。どちらも「何が書いてあるのか」が読めないまま、コピーして貼って、1文字ずれてエラーになる。この詰まりの原因は、書き方の違いに目を奪われて、中身が同じ形をしていることに気づけていないことです。
この記事の結論
- 設定ファイルの中身は「名前と値の組」と「値の並び」を入れ子にしたもので、JSON も YAML もこの同じ構造を書きます。
- JSON は波かっこ・角かっこ・引用符で区切りをはっきり書く形式で、機械が読みやすく、API のやり取りでよく使われます。
- YAML は字下げとハイフンで入れ子を表す形式で、人が読み書きしやすく、# でコメントも書けます。
- 値の種類は文字列・数・真偽・null・並び・入れ子の6つで、種類を取り違えるとエラーや意図しない動きになります。
- エラーの多くは「カンマの余り・不足」「引用符の閉じ忘れ」「字下げのずれ」なので、まず構造を目で追います。
設定ファイルとは何か｜「名前と値」を入れ子にしたもの
設定ファイルとは、プログラムや道具に「こう動いてほしい」を伝えるための文書です。人間向けの文章と違い、道具が読み間違えないように、書き方の決まりが厳密に定められています。
中身を分解すると、材料は3つしかありません。
- 名前と値の組：「region（名前）は ap-northeast-1（値）」のように、名札と中身を対にしたもの。
- 値の並び（リスト）：「80、443」のように、同じ種類のものを順に並べたもの。
- 入れ子：値の中にさらに「名前と値の組」や「並び」を入れること。引き出しの中に仕切り箱が入っている形です。
この3つを積み重ねると、どれだけ長い設定ファイルでも組み立てられます。長いファイルが読めないのは、材料が多いのではなく、どこからどこまでが1つの塊かが見えていないからです。
FOUR LAYERS設定ファイルの積み木
設定ファイルは4つの層の積み重ね。JSON も YAML も同じ
JSON
- 値（文字列・数・真偽・null）
- 名前と値の組
- 値の並び
- 入れ子（組や並びを中に入れる）
YAML
- 値（文字列・数・真偽・null）
- 名前と値の組
- 値の並び
- 入れ子（組や並びを中に入れる）
どちらの書き方でも組む層（土台となる層）
たとえるなら、設定ファイルは書類棚です。棚（入れ子）の中にファイルボックス（並び）があり、ボックスの中の各書類に名札（名前）と中身（値）が付いています。棚の見取り図が分かれば、JSON でも YAML でも、書類の探し方は同じです。
JSON の仕組み｜{ }・[ ]・引用符で区切りを書く
JSON は、区切りを記号で明示する書き方です。仕様は RFC 8259 に定められています。
{
"name": "web-server",
"port": 443,
"tags": ["prod", "web"],
"owner": {
"team": "infra",
"active": true
}
}
読み方の決まりは次のとおりです。
- 波かっこ
{ }は「名前と値の組」の集まりを囲みます。名前は必ず二重引用符で囲み、コロンで値とつなぎます。 - 角かっこ
[ ]は「値の並び」を囲みます。 - 組や値の間は、カンマで区切ります。
- 値の中にさらに波かっこや角かっこを置けば、入れ子になります。上の
ownerがその例です。
読むときは、外側の波かっこから始めて「この中に名前が4つある」と数え、次に各名前の値が何の種類かを見ます。tags の値は角かっこなので並び、owner の値は波かっこなので入れ子、と判定できます。
記号が多くて目がうるさい反面、区切りが明確なので、機械が曖昧さなく読めます。API で情報をやり取りする場面や、道具が自動で書き出す設定でよく使われるのは、この確実さのためです。
CHECK 1ここまでの確認
JSON で複数の値を順に並べるとき、全体を囲む記号はどれ?
答えと解説
答え: 2. 角かっこ [ ]
JSON では「名前と値の組」を波かっこ、「値の並び」を角かっこで囲みます。読み直すなら「JSON の仕組み」の章です。
YAML の仕組み｜字下げと - で同じ構造を書く
YAML は、記号を減らして字下げで構造を表す書き方です。仕様は YAML 1.2.2 に定められています。同じ内容を YAML で書くと次のとおりです。
# サーバーの設定
name: web-server
port: 443
tags:
- prod
- web
owner:
team: infra
active: true
JSON との対応は次のとおりです。
- 「名前: 値」の行が、名前と値の組です。コロンの後ろに空白を1つ置きます。
- 行頭のハイフン
-が、並びの1項目です。 - 親の項目より空白を深く書いた行が、その親の中身（入れ子）になります。上の
ownerの下の2行が、ownerの中身です。 #から行末まではコメントで、道具には読まれません。
波かっこがない代わりに、字下げが構造そのものです。字下げの深さを変えると、親子関係が変わります。YAML 1.2.2 の仕様は、環境ごとに扱いが違うため、字下げにタブを使ってはならないと定めています。空白で揃えるのが決まりです。
SAME SHAPE同じ設定の2つの書き方
波かっこは字下げに、角かっこはハイフンに対応する
JSON — 記号で区切る
{ } で名前と値の組、[ ] で並び、カンマで区切り、名前は二重引用符。コメントを書く記法は無い
YAML — 字下げで区切る
空白の深さで親子、行頭の - で並びの1項目、名前: 値 で組。# でコメントが書ける
CHECK 2ここまでの確認
YAML で「この項目はあの項目の中身だ」という親子関係を決めているものは何?
答えと解説
答え: 2. 行頭の空白の深さ
YAML は括弧を使わず、行頭の空白（字下げ）の深さで入れ子を表します。読み直すなら「YAML の仕組み」の章です。
同じ設定を JSON と YAML で並べると何が違うのか
前の2つの例は、同じ設定を別の書き方で書いたものです。構造は同じで、違うのは区切りの表し方です。
| 観点 | JSON | YAML |
|---|---|---|
| 区切り | { } [ ] , と引用符 |
字下げ、-、: |
| コメント | 文法に書き方が無い | # で書ける |
| 読みやすさ | 記号が多く長くなるが、塊の境目が明確 | すっきり読めるが、字下げを目で追う必要がある |
| 間違えやすい点 | カンマの余り・不足、引用符の閉じ忘れ | 字下げのずれ、タブの混入 |
| よく出会う場面 | API のやり取り、道具が書き出す設定 | 人が手で書く設定ファイル |
コメントの違いは実用上大きな差です。RFC 8259 の文法には、コメントを書く記号が定められていません。「なぜこの値にしたのか」をファイルの中に残したいときは、YAML のほうが向いています。
どちらが優れているという話ではなく、機械が読むものは JSON、人が書き足していくものは YAML、という分担が多いと覚えておくと、出会ったときに迷いません。
CHECK 3ここまでの確認
設定の意図をメモとして同じファイルに書き残せるのは、JSON と YAML のどちら?
答えと解説
答え: 2. YAML（# で書く）
YAML には
値の種類｜文字列・数・真偽・null・並び・入れ子
名前の右側に来る「値」には、種類があります。RFC 8259 は、値を文字列・数・真偽（true / false）・null・配列（並び）・オブジェクト（入れ子）と定めています。
| 種類 | JSON での書き方 | 意味 |
|---|---|---|
| 文字列 | "ap-northeast-1" |
文字の並び。二重引用符で囲む |
| 数 | 443 |
計算できる数。引用符で囲まない |
| 真偽 | true / false |
はい／いいえ |
| null | null |
「値が無い」ことを表す |
| 並び | ["a", "b"] |
値を順に並べたもの |
| 入れ子 | { "x": 1 } |
名前と値の組の集まり |
見落としやすいのは、"443" と 443 は別物という点です。引用符で囲むと文字列、囲まなければ数になります。道具は「数が来るはずの場所に文字列が来た」ことを嫌うことがあり、見た目が同じでも動きが変わります。YAML では引用符を省いて書ける場面が多いので、この取り違えがさらに起きやすくなります。YAML の細かい型の決め方は仕様の範囲が広いため、この記事では扱わず、迷ったら引用符で囲んで文字列にします。
THREE GATES読み込みの3つの門
設定ファイルはカンマ・引用符・字下げの門を通れて初めて読まれる
道具の読み込み（構文の検査）
- 1カンマ 通る項目の間だけにある
- 2引用符 止まる閉じ忘れがある
- 3字下げ 通る同じ階層が縦に揃っている
エラーはどこで起きるのか｜カンマ・引用符・字下げの3つの見方
設定ファイルのエラーの多くは、構造の読み間違いではなく、区切りの1文字のずれです。道具は人間のように「たぶんこの意味だろう」と補ってくれないので、規則に反した時点で読むのをやめます。見る場所は3つです。
カンマ（JSON）
JSON のカンマは、項目と項目の「間」に置く区切りです。次の2つがよくある間違いです。
{
"name": "web-server"
"port": 443
}
{
"name": "web-server",
"port": 443,
}
1つ目は項目の間にカンマが無く、2つ目は最後の項目の後ろに余計なカンマがあります。どちらも RFC 8259 の文法に反します。直し方は、各行の末尾を見て「次の項目が続くならカンマ、最後なら無し」を確かめることです。
引用符（JSON・YAML）
JSON の名前と文字列は二重引用符で囲みます。閉じ忘れると、そこから先が全部「文字列の続き」と読まれ、エラー位置が実際のミスの数行後に表示されることがあります。エラーが指す行より前も疑います。
字下げ（YAML）
YAML では、字下げが1つずれるだけで親子が変わります。
owner:
team: infra
active: true
この例は active の字下げが team と揃っていないため、読めません。揃っているのに意図と違う場所に入っている、という間違いもあります。直し方は、定規を当てるつもりで、同じ階層の行が同じ深さで始まっているかを縦に見ることです。タブが混ざっていないかも確かめます。
エラーを見たときの3つの順番
- まず、エラーが指す行の1つ前から読む。閉じ忘れは後ろの行に影響が出る。
- 次に、同じ階層が揃っているかを縦に見る（YAML）、カンマが「間」だけにあるかを見る（JSON）。
- 最後に、値の種類（引用符の有無）が意図どおりかを確かめる。
CHECK 4ここまでの確認
JSON の最後の項目の後ろにカンマを付けたファイルが読めなくなるのは、なぜ?
答えと解説
答え: 1. カンマの後ろには次の項目が来るという規則だから
JSON ではカンマは項目と項目の「間」に置く区切りで、後ろに何も続かないカンマは文法に反します。読み直すなら「エラーはどこで起きるのか」の章です。
文法の検査を助けてくれる道具もあります。エディタの構文チェックや、各道具が出す検証のメッセージです。ただし、メッセージを読むにも「どこが親で、どこが子か」の見取り図が要ります。この記事の3つの材料を頭に置いておけば、メッセージの指す場所が分かります。
この先どこで出会うか｜API・AWS CLI・IaC の入口
この記事で身につけた読み方は、次のような場面で、そのまま使えます。
- API とのやり取り：道具同士が情報を渡し合うときの形として、JSON がよく使われます。
- AWS CLI：コマンドの結果が JSON で返ってくることがあります。どの名前の下に欲しい値があるかを、入れ子をたどって探します。
- IaC（コードでインフラを書く）：構成を書いたファイルが YAML や JSON で書かれる道具があります。字下げと入れ子の読み方がそのまま効きます。
- アクセス権限のポリシー：権限の許可と拒否を書く文書も、名前と値の入れ子です。
これらは、書き方の細かい決まりは道具ごとに違っても、骨組みは「名前と値」「並び」「入れ子」の3つです。道具ごとの書き方は、それぞれの記事で扱います。
そして、設定ファイルは書き換えを重ねるものです。1文字のずれで動かなくなるなら、直前の版に戻せることが大切になります。次の記事では、版を並行して残す Git のブランチの仕組みを扱います。
READ ALSO — 未経験向け・段1 入口
Git のブランチとマージの仕組み｜main を直接触らない理由と、プルリクエスト・衝突の意味
最後にまとめます。
- 設定ファイルは、名前と値の組、値の並び、入れ子の3つでできています。
- JSON は記号で、YAML は字下げで、同じ構造を書きます。
- コメントを書けるのは YAML、区切りが明確なのは JSON です。
- エラーを見たら、カンマ・引用符・字下げの順に、構造を目で追います。
参照ソース
- RFC 8259: The JavaScript Object Notation (JSON) Data Interchange Format — JSON の文法（波かっこ・角かっこ・カンマ・引用符）と値の6種類、コメントの記法が定められていないことの根拠
- YAML Ain’t Markup Language (YAML) Version 1.2.2 — 字下げで構造を表すこと、字下げにタブを使ってはならないこと、
#によるコメントの根拠
