JSON・YAML・TOMLの違いと選び方|同じ設定を書き比べて分かる設定ファイルの特徴
アプリの設定ファイルを作るとき、JSON・YAML・TOML のどれで書けばよいか迷ったことはありませんか。3 つとも「キーと値の組み合わせ」「リスト」「入れ子」を表せる点は同じですが、コメントが書けるか、数値や日付をどう扱うか、書き間違えたときにどうなるかが大きく違います。
この記事では、同じ設定を JSON・YAML・TOML(と参考に INI)で書いて並べ、Python 3.12 で読み込んで本当に同じデータになるかを実行して確かめます。そのうえで、違いを比較表にまとめ、実際にどこで使われているか、どう選べばよいかを解説します。
- 同じ設定を 4 つの形式で書くと、どう見た目が変わるか
- コメント・型・入れ子・末尾のカンマ・日付の扱いの違い(比較表)
- package.json・pyproject.toml・GitHub Actions・Docker Compose で使われている形式
- YAML の「NO」が False になるなど、エラーにならない落とし穴
JSON・YAML・TOML とは
3 つとも、人が読み書きできる文字だけで「データの形」を表すための書き方(データ形式)です。それぞれ仕様(決まりごとをまとめた文書)があり、この記事では次の版を確認しています。
| 形式 | 拡張子 | 仕様 | ひとことで言うと |
|---|---|---|---|
| JSON | .json | RFC 8259 | JavaScript の書き方がもとになった、プログラム同士のデータ交換の定番。決まりが少なく厳密 |
| YAML | .yaml / .yml | YAML 1.2.2(2021 年 10 月) | インデント(字下げ)で入れ子を表す。記号が少なく人が読みやすいが、決まりが多い |
| TOML | .toml | TOML v1.0.0 | 設定ファイル向けに作られた形式。「[見出し]」と「キー = 値」で書く |
| INI(参考) | .ini など | 統一された仕様はない | Windows の昔からの設定ファイル。読み込むソフトごとに細かい決まりが違う |
TOML の仕様には「TOML is designed to map unambiguously to a hash table.」(あいまいさなく、ハッシュテーブル=キーと値の表に対応するよう設計した)と書かれています。YAML 1.2 は、JSON を完全に含む(JSON として正しい文書は YAML としても読める)ことを主な目的の 1 つにした版です。
なお、YAML のインデントやリストの詳しい書き方はこの記事では扱いません。ここでは「形式どうしの違い」と「選び方」に絞ります。
同じ設定を 4 つの形式で書いてみる
例として、Web アプリ「shop-api」の設定を書きます。アプリ名・デバッグの ON/OFF・ポート番号・タイムアウト秒数・接続を許可するホスト名のリスト、それにデータベースの接続先(入れ子)を持たせました。
JSON(config.json)
{
"app_name": "shop-api",
"debug": false,
"port": 8080,
"timeout": 2.5,
"allowed_hosts": ["localhost", "example.com"],
"database": {
"host": "db.local",
"port": 5432,
"user": "app"
}
}
全体を { } で囲み、キーは必ず「”」(ダブルクォート)で囲みます。項目の区切りは「,」で、最後の項目の後ろには付けません。コメントは書けないので、「アプリの設定」という説明も入れていません。
YAML(config.yaml)
# アプリの設定
app_name: shop-api
debug: false
port: 8080
timeout: 2.5
allowed_hosts:
- localhost
- example.com
database:
host: db.local
port: 5432
user: app
括弧も「”」もなく、いちばん短く書けます。database の下の 3 行は、スペース 2 つ分の字下げで「database の中身」であることを表しています。「#」から行末まではコメントです。
TOML(config.toml)
# アプリの設定
app_name = "shop-api"
debug = false
port = 8080
timeout = 2.5
allowed_hosts = ["localhost", "example.com"]
[database]
host = "db.local"
port = 5432
user = "app"
「キー = 値」の形で、文字列は「”」で囲みます。入れ子は字下げではなく、[database] という見出し(TOML では「テーブル」と呼びます)で表します。見出しの下は、次の見出しが来るまで database の中身です。
INI(config.ini、参考)
; アプリの設定
[app]
app_name = shop-api
debug = false
port = 8080
timeout = 2.5
allowed_hosts = localhost,example.com
[database]
host = db.local
port = 5432
user = app
見た目は TOML に似ていますが、INI には「リスト」がありません。そのため allowed_hosts は「,」でつないだ 1 つの文字列にしています。また、Python の configparser では、どのキーも何かのセクション([app] など)の中に書く必要があるため、[app] を足しています。
Python で読み込んで、同じデータか確かめる
上の 3 つ(JSON・YAML・TOML)を Python で読み込み、比べてみます。使うのは次の 3 つです。
- json:Python に最初から入っている(標準ライブラリ)
- tomllib:Python 3.11 で標準ライブラリに追加された。読み込み専用で、TOML を書き出す機能はない(公式ドキュメントに「This module does not support writing TOML.」とある)
- PyYAML:標準ライブラリではないので、
py -m pip install pyyamlで入れる。この記事では PyYAML 6.0.3 で確認
3 つの設定ファイルと同じフォルダーに、次の内容を compare.py という名前で保存します(ファイルはすべて UTF-8 で保存してください)。
import json
import tomllib
import yaml
with open("config.json", encoding="utf-8") as f:
from_json = json.load(f)
with open("config.yaml", encoding="utf-8") as f:
from_yaml = yaml.safe_load(f)
with open("config.toml", "rb") as f:
from_toml = tomllib.load(f)
print(from_json)
print(from_json == from_yaml)
print(from_json == from_toml)
PowerShell で、そのフォルダーに移動してから実行します。
py compare.py
{'app_name': 'shop-api', 'debug': False, 'port': 8080, 'timeout': 2.5, 'allowed_hosts': ['localhost', 'example.com'], 'database': {'host': 'db.local', 'port': 5432, 'user': 'app'}}
True
True
3 つとも、まったく同じ Python の dict(辞書)になりました。false は False(真偽値)、8080 は整数、2.5 は小数、ホスト名はリストとして読まれています。書き方は違っても、中身は同じデータを表せるということです。

tomllib だけ、ファイルを "rb"(バイナリーモード)で開いている点に注意してください。tomllib.load() はバイナリーで開いたファイルを受け取る決まりで、文字コードは tomllib が UTF-8 として読みます(TOML の仕様で、ファイルは UTF-8 と決まっています)。
INI は、どの値も文字列になる
INI のほうは、標準ライブラリの configparser で読みます。ini.py として保存します。
import configparser
config = configparser.ConfigParser()
config.read("config.ini", encoding="utf-8")
print(config["database"]["port"], type(config["database"]["port"]))
print(config.getint("database", "port"))
print(config.getboolean("app", "debug"))
print(config["app"]["allowed_hosts"])
py ini.py
5432 <class 'str'>
5432
False
localhost,example.com
ポート番号の 5432 が、整数ではなく文字列(str)として読まれています。configparser の公式ドキュメントにも、値の型は推測せず、すべて文字列として持つと書かれています。整数や真偽値が欲しいときは、getint()・getboolean() のように自分で変換を指定します。リストの allowed_hosts も、ただの文字列のままです。
JSON・YAML・TOML・INI の違い(比較表)
仕様と、上の実行結果をもとに違いをまとめます。YAML の欄は YAML 1.2.2 の仕様に沿った内容で、PyYAML の動きが違う点は後の「よくある間違い」で説明します。
| 項目 | JSON | YAML | TOML | INI |
|---|---|---|---|---|
| コメント | 書けない | 「#」で書ける | 「#」で書ける | 「;」「#」(configparser の初期設定。行の途中からは不可) |
| 文字列の引用符 | 必ず「”」 | 多くの場合は不要 | 必ず「”」か「’」 | 不要(引用符も値の一部になる) |
| 値の型 | 文字列・数値・真偽値・null・オブジェクト・配列 | JSON と同じ種類を表せる(書き方から型を推測する) | 文字列・整数・小数・真偽値・日時・配列・テーブル(null はない) | すべて文字列 |
| 入れ子の書き方 | { } と [ ] | インデント(字下げ) | [見出し] か { }(1 行で書く) | セクション 1 段だけ |
| 最後の項目の後ろの「,」 | エラー | ([ ] 形式のとき)PyYAML では書けた | 配列では書ける・{ } では書けない | (リストがない) |
| 日付・時刻 | 専用の型はない(文字列にする) | 1.2.2 の推奨スキーマには型がない | 日時・日付・時刻の型がある | 文字列 |
| 同じキーを 2 回書く | 「SHOULD be unique」(重複しないほうがよい)。Python では後の値が残る | 仕様上は不可。PyYAML では後の値が残る | エラー | configparser の初期設定ではエラー |
| 字下げの意味 | なし(見やすさのため) | あり(タブは使えない) | なし | なし |
特に差が出やすい項目を、実際の動きと一緒に見ていきます。
コメント:JSON だけ書けない
RFC 8259 の文法には、コメントの決まりがありません。JSON に // でコメントを書くと、Python の json モジュールではエラーになります(下の「末尾のカンマ」の実行結果の 1 行目)。設定の意味をファイルの中に書き残したいなら、YAML か TOML が向いています。
Python の pyproject.toml の形式を決めた PEP 518 でも、JSON を選ばなかった理由として「the syntax is more verbose than necessary while not allowing for comments」(必要以上に冗長で、コメントも書けない)と書かれています。
型:YAML は書き方から型を推測する
JSON と TOML は、"8080" と書けば文字列、8080 と書けば数値です。文字列は必ず引用符で囲むので、迷う余地がありません。
YAML は文字列に引用符がいらない代わりに、8080 は整数、false は真偽値、shop-api は文字列というように、書かれた文字の形から型を決めます。便利な反面、意図しない型になることがあります(後で実例を示します)。INI は逆に、何もかも文字列です。
入れ子:括弧・字下げ・見出し
入れ子が深くなると、JSON は括弧が増え、YAML は字下げが深くなります。TOML は [database.replica] のように見出しをドットでつなげば、字下げせずに深い入れ子を書けます。TOML の { }(インラインテーブル)は、仕様で 1 行に書くものとされているので、短いものだけに使います。
末尾のカンマ:JSON はエラー、TOML は配列だけ OK
最後の項目の後ろに「,」を付けたときの動きを、Python で確かめます。まず JSON です。json_errors.py として保存して実行します。
import json
samples = [
'{"port": 8080, // ポート番号\n "debug": false}',
'{"port": 8080, "debug": false,}',
'["localhost", "example.com",]',
"{'port': 8080}",
]
for text in samples:
try:
json.loads(text)
except json.JSONDecodeError as e:
print(e)
py json_errors.py
Expecting property name enclosed in double quotes: line 1 column 16 (char 15)
Expecting property name enclosed in double quotes: line 1 column 31 (char 30)
Expecting value: line 1 column 29 (char 28)
Expecting property name enclosed in double quotes: line 1 column 2 (char 1)
コメント(1 行目)、オブジェクトの末尾の「,」(2 行目)、配列の末尾の「,」(3 行目)、キーを「’」で囲んだもの(4 行目)は、どれもエラーです。メッセージが「ダブルクォートで囲んだキーが来るはず」となっているのは、「,」や「{」の後には次のキーが来るはずなのに、別の文字があったためです。
次に TOML です。toml_check.py として保存して実行します。
import tomllib
samples = [
'hosts = ["localhost", "example.com",]',
'db = { host = "db.local", port = 5432, }',
'port = 8080\nport = 9090',
'name = shop-api',
]
for text in samples:
try:
print(tomllib.loads(text))
except tomllib.TOMLDecodeError as e:
print("TOMLDecodeError:", e)
py toml_check.py
{'hosts': ['localhost', 'example.com']}
TOMLDecodeError: Invalid initial character for a key part (at line 1, column 40)
TOMLDecodeError: Cannot overwrite a value (at end of document)
TOMLDecodeError: Invalid value (at line 1, column 8)
- 1 行目:配列の末尾の「,」は OK。仕様にも「A terminating comma (also called a trailing comma) is permitted after the last value of the array.」とあります
- 2 行目:インラインテーブル
{ }の末尾の「,」はエラー。仕様で「not permitted」とされています - 3 行目:同じキーを 2 回書くとエラー(仕様で「Defining a key multiple times is invalid.」)
- 4 行目:文字列を「”」で囲み忘れるとエラー。YAML の感覚で書くと間違えやすいところです
日付・時刻:TOML だけ専用の型がある
TOML には、タイムゾーン付きの日時・タイムゾーンなしの日時・日付だけ・時刻だけの 4 種類の型があります。JSON には日付の型がなく、文字列として持つしかありません。dates.py で確かめます。
import json
import tomllib
import yaml
toml_text = """
released = 2026-10-18
updated = 2026-10-18T09:30:00+09:00
local = 2026-10-18T09:30:00
alarm = 07:30:00
"""
for key, value in tomllib.loads(toml_text).items():
print(key, repr(value))
print(yaml.safe_load("released: 2026-10-18"))
print(json.loads('{"released": "2026-10-18"}'))
py dates.py
released datetime.date(2026, 10, 18)
updated datetime.datetime(2026, 10, 18, 9, 30, tzinfo=datetime.timezone(datetime.timedelta(seconds=32400)))
local datetime.datetime(2026, 10, 18, 9, 30)
alarm datetime.time(7, 30)
{'released': datetime.date(2026, 10, 18)}
{'released': '2026-10-18'}
TOML の値は、Python の date・datetime・time になりました。+09:00 を付けた日時は、タイムゾーン(32400 秒=9 時間)付きで読まれています。JSON は文字列のままなので、日付として使うには自分で変換します。
YAML は少し複雑です。YAML 1.2.2 の推奨スキーマ(どの書き方をどの型とみなすかの決まり)には日付の型がありません。ところが PyYAML は 2026-10-18 を date として読みました。これは PyYAML が古い YAML 1.1 に沿っているためです(PyYAML の公式ページに「a complete YAML 1.1 parser」とあります)。同じ YAML ファイルでも、読み込むライブラリによって結果が変わることがある、と覚えておいてください。
それぞれが使われている代表的な場面
実務では、形式を自分で選ぶより「使うツールが形式を決めている」ことのほうが多いです。代表的なものを、公式ドキュメントで確認できた範囲でまとめます。
| ファイル | 形式 | 何に使うか | 公式ドキュメントの記述 |
|---|---|---|---|
| package.json | JSON | Node.js(npm)のプロジェクトの名前・依存パッケージ・scripts | 「must be actual JSON, not just a JavaScript object literal」(JavaScript の書き方ではなく、本物の JSON でなければならない) |
| pyproject.toml | TOML | Python のプロジェクトのビルド方法・名前・依存パッケージ・各ツールの設定 | PEP 518 で [build-system] と [tool]、PEP 621 で [project] が決められた(どちらも Final) |
| .github/workflows/*.yml | YAML | GitHub Actions のワークフロー(自動テストなど) | 「Workflow files use YAML syntax, and must have either a .yml or .yaml file extension.」 |
| compose.yaml | YAML | Docker Compose で動かすコンテナの構成 | 既定のファイル名は compose.yaml(推奨)か compose.yml。古い docker-compose.yaml・docker-compose.yml も読める |
pyproject.toml は、たとえば次のような形です。[project] の下に名前・バージョン・依存パッケージを書きます(キー名は PEP 621 で定められたもの)。
[build-system]
requires = ["setuptools"]
[project]
name = "shop-api"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = [
"pyyaml",
]
PEP 518 では、YAML を選ばなかった理由として、仕様が大きい(印刷すると 86 ページ)ことと、初期設定のままでは安全でない(任意のコードを実行できてしまう)ことが挙げられています。
どれを選べばよいか(選び方の目安)
まず「使うツールが決めているなら、それに従う」が大前提です。そのうえで、自分のプログラムの形式を選ぶときの目安は次のとおりです。
| こんなとき | おすすめ | 理由 |
|---|---|---|
| プログラム同士でデータをやり取りする(Web API の応答など) | JSON | ほぼすべての言語に読み書きの機能があり、決まりが少なく解釈がぶれにくい |
| 人が書く設定ファイルで、入れ子が浅い | TOML | コメントが書け、文字列は必ず引用符で囲むので型の勘違いが起きにくい。Python なら標準の tomllib で読める |
| 人が書く設定で、入れ子が深い・リストの中に表が並ぶ | YAML | 字下げだけで深い構造を短く書ける。ただし型の推測とインデントに注意 |
| プログラムが自動で書き出し、人も読む | JSON | Python なら標準の json で書き出せる(tomllib は書き出せない。YAML は PyYAML が必要) |
| 古いソフトの設定や、値がすべて文字列でよい簡単な設定 | INI | Python の configparser で読めるが、リストや入れ子が必要なら他の形式にする |
迷ったときは、「データの受け渡しなら JSON、人が書く設定なら TOML、使うツールが YAML を指定していれば YAML」と考えると大きく外れません。
よくある間違い・トラブル
YAML で「NO」や「1.10」が別の値になる
YAML は型を推測するため、文字列のつもりで書いた値が別の型になることがあります。PyYAML で確かめます(yaml_traps.py)。
import yaml
text = """
country: NO
answer: yes
version: 1.10
time: 12:30
zip: 0123
"""
print(yaml.safe_load(text))
py yaml_traps.py
{'country': False, 'answer': True, 'version': 1.1, 'time': 750, 'zip': 83}
| 書いた値 | つもり | PyYAML の結果 | 理由 |
|---|---|---|---|
NO | 国コード(ノルウェー) | False | YAML 1.1 では yes / no / on / off も真偽値 |
yes | 文字列 | True | 同上 |
1.10 | バージョン番号 | 1.1 | 小数として読まれ、末尾の 0 が消える |
12:30 | 時刻 | 750 | YAML 1.1 の 60 進数(12×60+30) |
0123 | 郵便番号の一部 | 83 | 0 で始まる数字は 8 進数 |
YAML 1.2.2 の Core スキーマでは、真偽値は true / True / TRUE / false / False / FALSE だけで、yes や NO は文字列です。上の結果は、PyYAML が YAML 1.1 の決まりで読んでいるために起きます。どのライブラリで読まれても同じ結果にしたいなら、文字列は「”」で囲むのが確実です。
5 つの値をすべて country: "NO" のように「”」で囲んで書き直すと、PyYAML でも 'NO'・'1.10'・'0123' などの文字列として読まれました。
GitHub Actions のワークフローの on: push も、PyYAML で読むとキーが True になります({'name': 'CI', True: 'push', ...} と表示されました)。自分のスクリプトでワークフローファイルを読むと、data["on"] では取り出せないので注意してください。
Docker Compose のポートを引用符なしで書く
上と同じ 60 進数の問題が、Docker Compose のポートの指定で起きます。Docker の公式リファレンスには「HOST:CONTAINER should always be specified as a (quoted) string, to avoid conflicts with YAML base-60 float.」(YAML の 60 進数と衝突しないよう、常に引用符で囲んだ文字列で書く)と書かれています。PyYAML で - 22:22 と - "22:22" を読むと、前者は 1342(22×60+22)、後者は '22:22' になりました。
services:
web:
image: nginx:alpine
ports:
- "8080:80"
同じキーを 2 回書いても気づかない
設定ファイルが長くなると、同じキーを 2 回書いてしまうことがあります。TOML は先ほどのとおりエラーになりますが、Python の json と PyYAML は、port を 8080 と 9090 の 2 回書いても、どちらもエラーにならず {'port': 9090}(後の値)になりました。前に書いた値が黙って消えるので、JSON は JSON 整形ツールのように重複キーを警告してくれるツールで確認すると安心です。
YAML を yaml.load で読み込む
PyYAML のドキュメントには「It is not safe to call yaml.load with any data received from an untrusted source!」(信頼できないデータを yaml.load で読むのは安全ではない)とあります。YAML には Python のオブジェクトを作る書き方があるためです。設定ファイルを読むときは、この記事のように yaml.safe_load を使います。
よくある質問
JSON のファイルは、YAML として読めますか?
YAML 1.2 は JSON を含むように作られているので、基本的には読めます。この記事の config.json を yaml.safe_load で読んだところ、json.load と同じ結果(比較して True)になりました。ただし、ライブラリによる細かな違いはあり得るので、JSON は JSON 用のライブラリで読むのが確実です。
Python で TOML ファイルを書き出すには?
標準の tomllib は読み込み専用です。Python の公式ドキュメントでは、書き出しには Tomli-W、コメントや書式を残したまま編集するには TOML Kit という外部パッケージが紹介されています(この記事では動作を確認していません)。プログラムから設定を書き出す必要があるなら、標準の json で書ける JSON にするのも選択肢です。
まとめ
- JSON・YAML・TOML は同じデータを表せる。Python で読むと、どれも同じ dict になった
- JSON はコメントと末尾のカンマが書けない。データ交換やプログラムの書き出しに向く
- TOML はコメントが書け、文字列は必ず引用符付き、日付の型もある。人が書く設定に向く
- YAML は短く書けるが、型の推測とインデントに注意。迷う値は「”」で囲む
関連する記事・ツール
- JSON整形ツール
- PythonでJSONを扱う方法|json.loads・dumpsの使い方とエラー対処
- .envと環境変数で秘密情報を守る|APIキーをGitに上げない方法と漏れたときの対処
- Markdownの書き方入門:README.mdを一から書いて学ぶ表示の仕組みとつまずく点
- Pythonの仮想環境venvの使い方|Windows・Linuxでの作成と有効化を解説
- YAMLの書き方入門|インデント・リスト・型の落とし穴とよくあるエラーの直し方
- Pythonのconfigparserの使い方|INIファイルの読み書きと型変換の落とし穴