JSON・YAML・TOMLの違いと選び方|同じ設定を書き比べて分かる設定ファイルの特徴

JSON・YAML・TOMLの違いと選び方|同じ設定を書き比べて分かる設定ファイルの特徴
hr
記事内に商品プロモーションを含む場合があります

アプリの設定ファイルを作るとき、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.jsonRFC 8259JavaScript の書き方がもとになった、プログラム同士のデータ交換の定番。決まりが少なく厳密
YAML.yaml / .ymlYAML 1.2.2(2021 年 10 月)インデント(字下げ)で入れ子を表す。記号が少なく人が読みやすいが、決まりが多い
TOML.tomlTOML 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 は小数、ホスト名はリストとして読まれています。書き方は違っても、中身は同じデータを表せるということです。

同じ設定の入れ子部分 database を 3 つの形式で書いた比較。JSON は波かっこで囲み、YAML は字下げで、TOML は角かっこの見出し database で中身を表す。3 つを Python の json.load、yaml.safe_load、tomllib.load で読むと同じ dict になり、キーは app_name が shop-api、debug が False、port が 8080、timeout が 2.5、allowed_hosts が 2 つのリスト、database が host、port、user の 3 つのキーを持つ dict。JSON と YAML、JSON と TOML を == で比べると、どちらも True になる。
図 1:書き方は違っても、読み込むと同じ dict になる

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 の動きが違う点は後の「よくある間違い」で説明します。

項目JSONYAMLTOMLINI
コメント書けない「#」で書ける「#」で書ける「;」「#」(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.jsonJSONNode.js(npm)のプロジェクトの名前・依存パッケージ・scripts「must be actual JSON, not just a JavaScript object literal」(JavaScript の書き方ではなく、本物の JSON でなければならない)
pyproject.tomlTOMLPython のプロジェクトのビルド方法・名前・依存パッケージ・各ツールの設定PEP 518 で [build-system] と [tool]、PEP 621 で [project] が決められた(どちらも Final)
.github/workflows/*.ymlYAMLGitHub Actions のワークフロー(自動テストなど)「Workflow files use YAML syntax, and must have either a .yml or .yaml file extension.」
compose.yamlYAMLDocker 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字下げだけで深い構造を短く書ける。ただし型の推測とインデントに注意
プログラムが自動で書き出し、人も読むJSONPython なら標準の json で書き出せる(tomllib は書き出せない。YAML は PyYAML が必要)
古いソフトの設定や、値がすべて文字列でよい簡単な設定INIPython の 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国コード(ノルウェー)FalseYAML 1.1 では yes / no / on / off も真偽値
yes文字列True同上
1.10バージョン番号1.1小数として読まれ、末尾の 0 が消える
12:30時刻750YAML 1.1 の 60 進数(12×60+30)
0123郵便番号の一部830 で始まる数字は 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 は短く書けるが、型の推測とインデントに注意。迷う値は「”」で囲む

関連する記事・ツール

ABOUT ME
hr
hr
エンジニアとして働いている hr です。仕事や資格勉強で「こんなツールがあれば」と感じたものを、無料Webツールと解説記事にして発信しています。
記事URLをコピーしました