アプリケーション開発などで設定ファイルを定義することが多いですが、データ記述言語の選定は、プロジェクトの保守性や事故防止に直結します。各フォーマットの特徴と戦略的な使い分けを考えた際のメモです。
0. XML (スコープ外)
タグ（<tag>）と属性（attr=""）を使い、非常に強固な階層構造を表現するデータ記述言語ですが、閉じタグの管理や属性・要素の使い分けなどが煩雑だったり、タグの構造情報自体が大きな割合を占めるため、読み書きする人間への負荷が高く、表現能力も設定ファイル向けとしてはオーバースペックです。そのため今回はスコープ外とします。
XML記述例
<?xml version="1.0" encoding="UTF-8"?>
<project>
<metadata>
<name>LegacySystem</name>
<version>1.0.0</version>
<description>Traditional markup format</description>
</metadata>
<server host="127.0.0.1">
<port>8080</port>
<timeout unit="seconds">30</timeout>
</server>
<features>
<feature id="f-01" enabled="true">
<name>Authentication</name>
</feature>
<feature id="f-02" enabled="false">
<name>Logging</name>
</feature>
</features>
<tags>
<tag>legacy</tag>
<tag>verbose</tag>
<tag>markup</tag>
</tags>
</project>
1. JSON (JavaScript Object Notation)
JSONの特徴
最も普及しているデータ交換形式です。JavaScriptのオブジェクト表記法をベースにしており、人間にも読めますが、基本的には「マシンが読み書きすること」に最適化された厳格な仕様を持ちます。
JSON記述例
{
"project": {
"name": "GlobalAPI",
"version": "1.0.0",
"description": "Standard data exchange format",
"active": true,
"tags": ["standard", "api", "universal"],
"server": {
"host": "127.0.0.1",
"port": 8080,
"timeout": 30
},
"features": [
{
"id": "f-01",
"name": "Auth",
"enabled": true
},
{
"id": "f-02",
"name": "Log",
"enabled": false
}
],
"author": null
}
}
JSONのメリット/デメリット
- メリット: 圧倒的な普及率。パーサが全ての言語に標準搭載されており高速。仕様が厳格で曖昧さがない。
- デメリット: コメントが書けない。末尾カンマが許されない。手書きすると構文エラーを起こしやすい。
2. JSON5
JSON5の特徴
JSONの「人間にとって不便な点」を解消した拡張版です。ECMAScript 5.1の構文を取り入れており、JavaScriptのソースコードに近い感覚で記述できます。
JSON5記述例
{
// プロジェクトの基本情報
project: {
name: "ModernApp",
version: "2.1.0",
/* 複数行のコメントも
記述可能 */
description: "Human-friendly JSON extension",
// 鍵括弧の省略が可能
tags: [
"extension",
"config",
"relaxed", // 末尾カンマが許容される
],
server: {
host: '127.0.0.1', // シングルクォート可
port: 8080,
timeout: Infinity, // 数値表現の拡張
},
// 16進数も記述可能
debug_mask: 0xFF,
}
}
JSON5のメリット/デメリット
- メリット: コメントが書ける。末尾カンマや引用符の省略により、編集のストレスが激減する。
- デメリット: JSONほど標準化されていない。パースに別途ライブラリが必要な場合が多い。
3. YAML (YAML Ain't Markup Language)
YAMLの特徴
インデント（空白）を使って構造を表現する形式です。記号が少なく、ドキュメントのような見た目が特徴で、インフラ構成管理などで多用されます。
YAML記述例
# アンカーによる共通設定
common_config: &base
adapter: postgres
encoding: utf-8
development:
<<: *base
database: dev_db
host: localhost
test:
<<: *base
database: test_db
# 長文テキストの保持
setup_script: |
#!/bin/bash
echo "Setting up environment..."
npm install
npm start
# リスト構造
services:
- name: web
image: nginx:latest
ports:
- "80:80"
- name: redis
image: redis:alpine
YAMLのメリット/デメリット
- メリット: 可読性が非常に高い。アンカー/エイリアスによるDRY（再利用）が可能。長文の埋め込みに強い。
- デメリット: インデント一つで構造が変わる。型推論が曖昧で、「NO」が「false」になる等の事故（ノルウェー問題）が起きやすい。仕様が肥大化しておりセキュリティリスクがある。
4. TOML (Tom's Obvious, Minimal Language)
TOMLの特徴
「明快で最小限」を目指した、設定ファイルに特化した形式です。INIファイルを進化させたような構造で、行ベースの分かりやすい記述が特徴です。
TOML記述例
[project]
name = "StableConfig"
version = "3.5.2"
description = "Clear and minimal configuration"
# 日付・時刻が標準サポート
release_date = 2026-03-27T12:00:00Z
[database]
server = "192.168.1.1"
ports = [ 8000, 8001, 8002 ]
connection_max = 5000
enabled = true
# 階層構造（テーブルの配列）
[[plugins]]
name = "auth"
priority = 1
[[plugins]]
name = "cache"
priority = 5
[owner]
name = "Admin User"
organization = "OpenSource Corp"
TOMLのメリット/デメリット
- メリット: 型が明確（日付・時刻等）。重複キーを許さない厳格な設計。Gitの差分（diff）が見やすくコンフリクトが起きにくい。
- デメリット: 階層が極端に深いデータ（4層以上など）を記述すると、キー名が冗長になり可読性が下がる。
どれにするか：YAMLは除外する
YAMLは「人間が読むための文書」と「コンピュータが読むためのデータ」のギリギリの妥協点といえる設計のため一見便利ですが、インデントミスによるサイレントエラーや型推論の罠が多く、さらにデータ記述言語の枠を超えてロジックを持たせようとしすぎているため、特に大規模なチーム開発では「動かして初めてミスに気づく」という事態を招きがちです。
すなわち現代の設計において、YAMLは「リスクが高く、中途半端な存在」になりつつあると考えます。
そのため、安全性を重視するなら、以下の2択に絞るのが賢明と考えます。
- JSON5: 構造が複雑（ツリー状）なデータを人間が管理したい場合。
- TOML: アプリケーションの動作パラメータを明確に定義したい場合。
使い分け
1. 目的別の使い分け
- 「データ」を定義するなら JSON5
- UIのレイアウト定義、複雑な入れ子構造を持つマスタデータなど。
- JavaScript/TypeScriptプロジェクトの開発用設定。
- ファイル全体の構文チェックの堅朗性を求める場合(読み込み側のチェックが弱い等)。
- 「設定」を定義するなら TOML
- サーバーのポート、タイムアウト、DB接続先などのフラットな設定項目。
- 非プログラマや運用担当者が直接書き換える可能性があるファイル。
2. JSON5で書いてJSONに変換する手法
「JSON5の書きやすさ」と「JSONの互換性」を両立させる運用としては、開発時はコメントを書き込めるJSON5で管理し、CI/CDプロセスやビルド時に json5 CLIツール等を使って標準のJSONへ変換(コンパイル)することで、実行環境側には手を加えずに、運用効率だけを最大化できます。
