JSON・YAML・CSV・Markdown 比較チートシート｜決定マトリクスと用途別の使い分け

JSON・YAML・CSV・Markdown はどれも「テキストで書ける構造を持ったデータ形式」ですが、想定する用途も得意な構造も大きく違います。設定ファイルに CSV を使うとデータが直線的にしか並べられず、API レスポンスに YAML を使うと厳密さが足りず、表データを JSON で交換すると行データが冗長になります。Markdown は人間が読むための文書としては最強ですが、機械可読データの一次保存先として扱うとあとで困ります。

この記事は「どの形式を使えばいいか」を 1 ページで判断するためのチートシートです。クイック決定マトリクスから始め、機能比較表、コメント対応、パーサー、用途別の決定マトリクス、よくある誤った選択、LLM コンテキストでの選び方、そして仕様情報までを 1 枚で参照できる構成にしました。

クイック決定マトリクス — どの形式を選ぶか

迷ったらここを見てください。代表的な用途と推奨形式の対応表です。

クイックに切り分けると次のようになります。マシン間のデータ交換は JSON、人が手で編集する設定は YAML、表形式は CSV、人が読む文書は Markdown です。あとは細部の例外で形式を選び直します。

まず試す — ブラウザで 4 形式を変換して違いを見る

違いは説明よりも、同じデータを 4 形式で並べて見るのが早いです。FormatArc の 7 つのツールはすべてブラウザ内で動作し、入力したデータは外部サーバーには送信されません。社内データや API レスポンスをそのまま貼り付けて試せます。

• JSON Formatter — JSON の整形・検証
• YAML to JSON / JSON to YAML — YAML と JSON の相互変換
• CSV to JSON — 表データを構造化 JSON へ
• CSV to Markdown — 表データを Markdown テーブルへ
• Markdown to HTML / HTML to Markdown — 文書形式の相互変換

機密データをアップロード型のオンラインツールに貼ることに不安があるときの選択肢として、オンライン変換ツールの安全性 で比較の枠組みをまとめています。

この記事で扱う 4 形式と扱わない形式

本記事は JSON・YAML・CSV・Markdown の 4 つに絞って比較します。Web 開発・設定ファイル・データ交換・ドキュメントの 4 領域で最も登場頻度が高い組み合わせで、FormatArc がブラウザ内で相互変換できる範囲でもあるためです。

スコープ外として扱う形式は次のとおりです。

• XML — 仕様としては有力ですが、新規プロジェクトでの採用は減少傾向です。SOAP / RSS / SVG / Office Open XML など既存資産との連携が必要なときに登場します
• TOML — Rust の Cargo や Python の pyproject.toml で使われる設定向け形式です。YAML / JSON5 と用途が重複し、Web 領域では出番が限定的です
• Parquet — 列指向のバイナリ形式で、ビッグデータ処理向けです。テキスト形式の本記事のスコープからは外れます
• XLSX / ODS — スプレッドシートのバイナリ形式です。CSV との往復は本記事でも触れます

XML や TOML を含む 5 形式比較は他の競合記事に多数あります。本記事は Markdown を 1 級市民として扱う 4 形式比較に絞り、Web フロントエンド・API・LLM コンテキスト・技術ドキュメントの現代的な用途に最適化しています。

同じデータを 4 形式で書いてみる

ユーザー 2 件 (名前・年齢・スキル一覧) を 4 形式でそれぞれ表現します。同じ情報を入れたときに、どこが違うのか、どこが共通なのかが視覚的にわかります。

JSON 版

{
  "users": [
    { "name": "Alice", "age": 30, "skills": ["Python", "Go"] },
    { "name": "Bob",   "age": 25, "skills": ["JavaScript"] }
  ]
}

YAML 版

users:
  - name: Alice
    age: 30
    skills:
      - Python
      - Go
  - name: Bob
    age: 25
    skills:
      - JavaScript

CSV 版

CSV は階層構造を直接表現できないため、skills をどこかで平坦化する必要があります。代表的な手段は 3 つで、; などで結合する、複数列に展開する、別テーブルに分離する、です。最も簡素な「結合」方式は次のようになります。

name,age,skills
Alice,30,Python;Go
Bob,25,JavaScript

Markdown 版

Markdown は機械可読データ形式ではなく文書形式なので、構造の表現は GFM の表に頼ります。

| name  | age | skills      |
|-------|-----|-------------|
| Alice | 30  | Python, Go  |
| Bob   | 25  | JavaScript  |

同じ情報を入れた結果、表現の自然さと文字数が違ってきます。JSON は厳密で機械が読みやすい、YAML は人間が読みやすい、CSV は表形式に強いが入れ子に弱い、Markdown はレンダリングしたときの見栄えに強いがネスト構造には弱い、という違いがそのまま見えます。

4 形式の機能マトリクス

各形式が「何を表現できて、何を表現できないか」を整理した一次マトリクスです。

JSON と YAML は同じデータモデル (オブジェクト + 配列 + プリミティブ) を共有しているため相互変換が容易です。FormatArc では YAML to JSON と JSON to YAML の双方向ツールを提供しています。2 形式の細かい違いは YAML と JSON の違い で深堀りしています。

コメント対応マトリクス

設定ファイル選びで効いてくるのが、コメントを書けるかどうかです。標準と派生実装で挙動が分かれるので整理します。

JSON でコメントを書きたい場面は多いですが、標準 JSON に書くとパースエラーになります。詳細と回避策は JSON にコメントを書ける？ でまとめています。

パーサーエコシステム比較

実装するときに「標準ライブラリで読めるか」「サードパーティが必要か」は判断軸になります。主要言語の対応状況を整理します。

JSON と CSV はほとんどの主要言語で標準ライブラリが入っています。YAML と Markdown はサードパーティ依存ですが、デファクトのライブラリが安定しています。FormatArc は Node.js エコシステムから yaml ・ papaparse ・ marked ・ turndown ・ remark をブラウザに持ち込んで、サーバーを経由せず変換を完結させています。

用途別の推奨フォーマット決定マトリクス

抽象的な比較表よりも、現場で発生する具体的な用途で表を引いたほうが速いことがあります。

Markdown 表は手書きが面倒なので、CSV や JSON を一次データとして持っておき CSV to Markdown で表に変換すると保守しやすいです。具体的な手順は GitHub README に表を作る で扱っています。

よくある誤った選択

複数のプロジェクトで繰り返し見る、形式選びの典型的な失敗です。

CSV で入れ子データを扱う

{ "user": { "address": { "city": "Tokyo" } } } のような階層構造を CSV で持つと、平坦化のルールを別途決める必要があり、読み込み時に逆の組み立てが必要になります。階層が必要なら最初から JSON か YAML を選ぶか、別テーブルに分離してリレーショナルモデルにしたほうが楽です。

YAML の暗黙型変換に踏み抜く

YAML 1.1 では no yes on off がブール値に推論されました。これがいわゆる「ノルウェー問題」で、国コード NO が false に変わってしまう事故です。YAML 1.2 では一部修正されましたが、現役のパーサーには 1.1 互換モードを持つものも多く、文字列として確実に扱いたい値は引用符で囲んでおくのが安全です。

country: "NO"   # 安全 — 文字列として確定
country:  NO    # YAML 1.1 互換パーサーでは false に化ける可能性

JSON にコメントを書く

VS Code の settings.json がコメントを許すため「JSON にもコメントを書ける」と思われがちですが、これは JSONC という派生方言です。標準 JSON (RFC 8259) はコメントを許さず、JSON.parse でパースエラーになります。コメントを書きたい場面では JSON5 / JSONC / YAML を選ぶか、別ファイルに分離します。

CSV のフォーマット差を軽視する

RFC 4180 はリファレンスではありますが、現場の CSV は方言だらけです。区切り文字 (, / \t / ; / |)、行末コード (LF / CRLF)、引用符の有無、BOM、文字コード、ヘッダー有無、改行を含む値のエスケープ — どれもパーサーごとに挙動が違うことがあります。「シンプル」と思って書いたら相手のシステムで読めなかった、はよくある話です。サンプルデータで両端の挙動を確認してから本番投入してください。

Markdown を機械可読データとして使う

Markdown はあくまで文書形式で、機械が安定して解析できる構造を持つデータ形式ではありません。Markdown 表はパーサーごとに挙動の差があり、たとえばパイプ文字を含むセルやセル内改行は GFM 拡張なしだと崩れます。レンダリング先に依存する話の詳細は Markdown 表が表示されない を参照してください。

Markdown 表が CommonMark 標準だと思う

Markdown 表は CommonMark には含まれず、GFM (GitHub Flavored Markdown) の拡張です。レンダリング先が CommonMark 厳格モードだと、Markdown 表は段落として解釈されます。Zenn・Qiita・GitHub は GFM 寄り、はてなブログや一部の Wiki エンジンは方言差があります。詳しくは CommonMark vs GFM の違い で整理しています。

LLM コンテキストでの選択

ChatGPT・Claude・Gemini にコンテキストを渡すときの一次選択は Markdown です。HTML と比べてトークン数は概ね 3 分の 1 から 10 分の 1 ほどに収まり、表・リスト・コードブロックの抽出精度も上回ります。一方、LLM の構造化出力 (function calling / JSON mode) は JSON が前提なので、入力は Markdown・出力は JSON という非対称な構成が現実的です。

YAML はインデントが LLM のトークナイザに対して不利になりやすく、また暗黙型変換で「文字列のつもりが真偽値」事故も起きるため、LLM 入出力としては避けるのが無難です。詳しい比較とトークン実測は LLM に渡すなら Markdown か HTML か で扱っています。

仕様と歴史

決定の根拠を確かめたいときに参照してください。

JSON と CSV は RFC が安定していますが、YAML と Markdown は仕様の派生 (YAML 1.1 vs 1.2、CommonMark vs GFM vs MultiMarkdown vs Pandoc) を意識する必要があります。実装側の互換性確認が必要な場面では、本記事の他のセクションも参照してください。

各形式の基礎から学びたい場合は次の記事を参照してください。

• JSON とは — JSON の文法と用途
• YAML とは — YAML の文法と用途
• CSV とは — CSV の文法と用途

FormatArc の 7 ツールで変換する

形式間を行き来する典型ルートは次の 7 つです。FormatArc はすべてブラウザ内で動作し、入力したデータはサーバーに送信されません。

組み合わせると、たとえば「API レスポンスの JSON → YAML に変換して設定ファイルに転用」「Excel の表 → CSV エクスポート → Markdown 表に変換して README に貼る」「Web ページの HTML → Markdown に変換して ChatGPT に渡す」といった一連のワークフローが、すべてブラウザ内で完結します。

まとめ

迷ったときの最終チェックリストです。

• マシン間のデータ交換: JSON
• 人間が編集する設定ファイル: YAML
• 表データ: CSV
• 人間が読む文書: Markdown
• LLM 入力: Markdown / LLM 出力: JSON

形式は「正しい・正しくない」で選ぶものではなく、「何を最適化するか」で選ぶものです。可読性・厳密さ・パーサーの広さ・コメント対応・LLM トークン効率 — それぞれの軸で 4 形式は得意分野が違います。本記事のマトリクスを 1 つの判断台帳として、プロジェクト初期の形式選びに使ってください。

仕様情報のリファレンスは次のとおりです。

• RFC 8259: The JavaScript Object Notation (JSON) Data Interchange Format
• YAML 1.2.2 Specification
• RFC 4180: Common Format and MIME Type for Comma-Separated Values (CSV) Files
• CommonMark Specification
• GitHub Flavored Markdown Spec