オブジェクトの配列になっている JSON を Markdown のテーブルにしたい。そんなときに一番崩れにくいのは、いったん CSV を経由してから CSV to Markdown に渡す方法です。JSON を直接 Markdown 表に変換するツールも世の中にはありますが、ネストや欠損キーが混ざると結果が崩れやすく、何が起きたか追いにくくなります。CSV を一段挟むと、列と行の対応が目で確認できる状態になるので、結果が安定します。
この記事では、JSON の構造を確認するところから、CSV への変換、Markdown テーブルの生成、そして API レスポンスやネストした JSON への対処までを順番に説明します。処理はすべてブラウザ内で完結するため、API のレスポンスや社内データを貼り付けても外部サーバーには送信されません。
結論: JSON は CSV を経由して Markdown 表にする
先に手順の全体像を示します。
- JSON Formatter で JSON を整形し、オブジェクトの配列になっているか確認する
- 配列を CSV に変換する（各オブジェクトのキーが列ヘッダー、各要素が 1 行になる）
- CSV を CSV to Markdown に貼り付けてテーブルを生成する
FormatArc には JSON をそのまま Markdown 表に変換するボタンはありません。代わりに、整形ツールと CSV 変換ツールを組み合わせると、どの環境でも崩れない GFM 互換のテーブルが作れます。CSV を中間表現にすることで、列のずれや欠損をその場で確認できるのが利点です。
Markdown テーブルに向く JSON の形
Markdown のテーブルは「列ヘッダー + 行」という二次元の表です。そのため、表化しやすい JSON は同じ構造のオブジェクトが並んだ配列です。
[
{ "name": "Mika", "role": "admin", "active": true },
{ "name": "Noah", "role": "viewer", "active": false }
]
このとき、各オブジェクトのキー（name / role / active）が列ヘッダーになり、配列の各要素が 1 行になります。上の JSON は次のテーブルに対応します。
| name | role | active |
| --- | --- | --- |
| Mika | admin | true |
| Noah | viewer | false |
逆に、単一のオブジェクト（配列に入っていない { ... }）はそのままでは行になりません。キーと値の 2 列の表にするか、[ { ... } ] のように配列で包んでから変換します。
手順: JSON を Markdown テーブルに変換する
ステップ 1: JSON を整形して構造を確認する
API のレスポンスやログから取り出した JSON は、改行のない 1 行になっていることが多くあります。まず JSON Formatter に貼り付けて整形し、本当にオブジェクトの配列になっているか、全要素が同じキーを持っているかを目で確認します。
構文エラーがあると後続の変換でつまずくので、ここでエラーが出た場合は JSON Parse Error の解決方法 を参照してください。// などのコメントが混ざっている場合は JSON コメントの書き方 を確認します。
ステップ 2: 配列を CSV に変換する
整形して構造を確認できたら、配列を CSV の形に直します。やることは次の 2 つだけです。
- 1 行目にキーをカンマ区切りで並べてヘッダーにする
- 各オブジェクトの値を同じ順番でカンマ区切りに並べて 1 行ずつ書く
先ほどの JSON なら、こうなります。
name,role,active
Mika,admin,true
Noah,viewer,false
値にカンマや改行が含まれている場合は、その値を二重引用符 "..." で囲みます。CSV の基本的な書き方については CSVとは も参照してください。逆に CSV を JSON に戻したい場合は CSV to JSON 変換ガイド で扱っています。
ステップ 3: CSV to Markdown でテーブルを生成する
CSV ができたら CSV to Markdown に貼り付けて実行します。
右側に GFM 互換の Markdown テーブルが出力されます。区切り線も列幅も自動で揃うので、そのままコピーして README や Issue、ドキュメントに貼れます。変換の仕組みやエッジケースについては CSV を Markdown テーブルに変換する方法 で詳しく説明しています。
API レスポンスの JSON を表にする
curl で叩いた API のレスポンスを、そのまま表にして共有したい場面があります。流れは上の手順と同じで、curl の出力を整形してから CSV を経由します。
curl -s https://api.example.com/users | jq .
レスポンスがオブジェクトの配列であれば、そのまま JSON Formatter に貼り付けて整形し、ステップ 2 以降に進めます。レスポンス全体が { "data": [ ... ] } のように配列を内側に持つ形なら、表にしたい配列部分（data の中身）だけを取り出します。jq を使うなら jq '.data' で配列だけを取り出せます。
curl のレスポンス整形そのものについては、jq・Python・CLI・ブラウザの 4 通りをまとめた curl の JSON を整形する方法 を参照してください。
ネストした JSON をどう扱うか
実際の API レスポンスは、値の中にさらにオブジェクトや配列が入っていることがよくあります。
[
{ "name": "Mika", "address": { "city": "Tokyo", "zip": "100-0001" } }
]
Markdown のテーブルは二次元の表なので、入れ子になった構造をそのままセルに入れることはできません。対処の方向性は 2 つです。
平坦化してから表にする
ネストしたキーを address.city のようなドット記法に展開し、フラットな構造に直してから CSV にします。
name,address.city,address.zip
Mika,Tokyo,100-0001
この「平坦化」は手作業でもできますが、要素数が多いときは jq の to_entries や、Python の pandas.json_normalize() のような関数で展開すると確実です。平坦化したあとは、これまでと同じく CSV を経由して CSV to Markdown に渡します。
ネストした値を文字列としてセルに入れる
平坦化せず、ネスト部分を 1 つの文字列としてセルに収める方法もあります。address の値を {"city":"Tokyo","zip":"100-0001"} のような JSON 文字列にして 1 列に入れます。この場合、文字列の中にパイプ記号 | や改行が含まれているとテーブルが崩れるので、CSV の段階で値を二重引用符で囲んでおきます。CSV to Markdown はセル内のパイプを自動でエスケープし、改行を半角スペースに置換するため、貼り付け側で細かい処理を気にする必要はありません。
列の配置を指定する
GFM のテーブルは、区切り線に : を付けることで列ごとの配置を指定できます。
| name | count |
| :--- | ---: |
| Mika | 12 |
| Noah | 340 |
:--- で左寄せ、:---: で中央、---: で右寄せです。数値の列を右寄せにすると桁が揃って読みやすくなります。ただし、この配置指定が反映されるかは表示側の Markdown レンダラーによって異なります。GitHub では正しく動作しますが、すべての環境で同じ見た目になるとは限らない点には注意してください。配置やエスケープを含む記法の詳細は Markdown 表の書き方 にまとめています。
よくあるハマりどころ
キーが要素ごとに揃っていない
配列の要素によって持っているキーが違う場合、どの列を表に出すかで結果が変わります。全要素のキーの和集合を列にすると、値がない箇所が空セルになります。先頭要素のキーだけを基準にすると、後ろの要素にしかないキーは表から漏れます。CSV を作る段階で、列をどう揃えるかを決めておくと安定します。
真偽値・null・数値の扱い
true / false / null や数値は、CSV に書き出すとそのまま文字として並びます。Markdown テーブル上でも文字列として表示されるため、見た目の意味は保たれます。空の値は空セルになります。
セル内の改行とパイプ
値の中に改行やパイプ記号が含まれていると、そのままでは列区切りと衝突してテーブルが崩れます。CSV の段階で値を二重引用符で囲んでおけば、CSV to Markdown 側で改行とパイプを安全に処理します。
よくある質問
JSON をアップロードする必要はありますか？
ありません。FormatArc の変換はすべてブラウザ内で動作します。API のレスポンスや社内データを貼り付けても、データが外部サーバーに送信されることはありません。
なぜ CSV を経由するのですか？
CSV を中間表現にすると、列ヘッダーと各行の対応が目で確認できる状態になります。JSON を直接表に変換するとネストや欠損キーで結果が崩れたときに原因を追いにくいですが、CSV を一段挟むことで、どの列がずれているかをその場で直せます。
ネストした JSON はそのまま表にできますか？
そのままでは表になりません。address.city のようなドット記法で平坦化するか、ネスト部分を JSON 文字列として 1 つのセルに収めてください。手順はこの記事の「ネストした JSON をどう扱うか」で説明しています。
まとめ
JSON をきれいな Markdown テーブルにする近道は、CSV を経由することです。JSON Formatter で構造を確認し、配列を CSV に直し、CSV to Markdown に貼り付ければ、GFM 互換のテーブルがそのままコピーできる形で出力されます。ネストや API レスポンスのように一筋縄でいかないケースでも、平坦化という一手間を挟めば同じ流れで処理できます。
できあがった Markdown テーブルを LLM のコンテキストとして渡す場合は、HTML より Markdown のほうがトークン効率と抽出精度の面で有利です。実測の比較は LLM に渡すなら Markdown か HTML か を参照してください。CSV からの変換をもっと深く知りたい場合は CSV を Markdown テーブルに変換する方法 もどうぞ。