3つの形式が企画会議に入ってきます。JSONは何でも処理できると言います。CSVは速くてスリムだと言います。 TOONはAIと話すためにここにいると言います。彼らは皆正しいです — 異なる仕事のために。 苛立たしい部分はこれらの形式が存在することではなく、ユースケースに間違ったものを選ぶと 実際に具体的なコストがかかることです：冗長なペイロード、壊れたインポート、高価なLLM請求書、 または解析の頭痛。このガイドは選択するための明確なフレームワークを提供します。

各形式の簡単なプロフィール

JSON (JavaScript Object Notation)は2000年代初頭にJavaScriptから生まれ、そのシンプルさと表現力から Web APIのための主要な形式になりました。ネストされた構造をネイティブに処理し、 追加の作業なしに文字列、数値、ブール値、nullを区別し、 RFC 8259で 規定されています。すべての現代の言語にはファーストクラスのJSONライブラリがあります。

CSV (Comma-Separated Values)はWebより古いです。 RFC 4180で定義されており、 フラットな表形式データの事実上の共通語です。ExcelやGoogle Sheets、NumbersでCSVを開けばそのまま動作します。 純粋なフラットテーブルには、存在する中で最もコンパクトで普遍的にインポートできる形式です。

TOONは LLMワークフロー専用に構築された新しい形式です。両方からインスピレーションを得ています — CSVと同様に 表形式データにはヘッダー一度だけ-その後行の構造を使用しますが、JSONと同様にネストされたオブジェクトと 配列もエンコードできます。そのデザイン全体は、大規模言語モデルとの間でデータを渡す際の トークン数の最小化に向けられています。

3つの形式で同じデータ

これを具体的にするために、ネストされたspecsオブジェクトを含む製品カタログを使いましょう — 3つの形式すべてを意味のある形でテストする現実世界の形状。電子機器店からの4つの製品です：

JSON — 表現力があり、ネストを自然に処理しますが、繰り返し行データには冗長：

json
[
  {
    "id": "P001",
    "name": "Wireless Headphones",
    "category": "Audio",
    "price": 79.99,
    "inStock": true,
    "specs": { "weight": "250g", "connectivity": "Bluetooth 5.2", "battery": "30h" }
  },
  {
    "id": "P002",
    "name": "USB-C Docking Station",
    "category": "Peripherals",
    "price": 129.99,
    "inStock": true,
    "specs": { "ports": 11, "maxPower": "100W", "display": "4K@60Hz" }
  },
  {
    "id": "P003",
    "name": "Mechanical Keyboard",
    "category": "Input",
    "price": 94.99,
    "inStock": false,
    "specs": { "layout": "TKL", "switches": "Cherry MX Red", "backlight": "RGB" }
  },
  {
    "id": "P004",
    "name": "27" IPS Monitor",
    "category": "Display",
    "price": 299.99,
    "inStock": true,
    "specs": { "resolution": "2560x1440", "refreshRate": "165Hz", "panel": "IPS" }
  }
]

CSV — コンパクト、Excel対応ですが、ネストされたspecsオブジェクトは フラット化する必要があります。標準的な表現方法がないため、ネストを失うかセルに文字列として詰め込むかになります：

text
id,name,category,price,inStock,specs_weight,specs_ports,specs_layout,specs_resolution
P001,Wireless Headphones,Audio,79.99,true,250g,,,
P002,USB-C Docking Station,Peripherals,129.99,true,,11,,
P003,Mechanical Keyboard,Input,94.99,false,,,TKL,
P004,27" IPS Monitor,Display,299.99,true,,,,2560x1440
CSVのスパースな列に注目してください。各製品がスペックキーが異なるため、 すべての可能なスペックフィールドのための列を作成しなければなりません — そしてほとんどの行は ほぼ空です。これが非均一なネストデータにCSVを使う場合の根本的な問題です。

TOON — ヘッダーは一度だけ宣言、行はコンパクト、ネストされたオブジェクトはインラインでエンコード：

text
products[4]{id,name,category,price,inStock,specs}:
  P001,Wireless Headphones,Audio,79.99,true,{weight:250g,connectivity:Bluetooth 5.2,battery:30h}
  P002,USB-C Docking Station,Peripherals,129.99,true,{ports:11,maxPower:100W,display:4K@60Hz}
  P003,Mechanical Keyboard,Input,94.99,false,{layout:TKL,switches:Cherry MX Red,backlight:RGB}
  P004,27" IPS Monitor,Display,299.99,true,{resolution:2560x1440,refreshRate:165Hz,panel:IPS}

各形式の弱点

失敗モードを理解することは強みを知ることと同じくらい重要です。

  • JSONはテーブルで失敗します。各行ですべてのキー名を繰り返すことは本当に 無駄です。各行に8つのキーがある1000行のデータセットでは、"id"、"name"、"price"などが それぞれ1000回書かれます。LLM入力ではこれが直接トークンコストに変換されます；人間の 検査にとってはただのノイズです。
  • CSVはネストデータで失敗します。形式にはネストの概念がありません。 ネストされたオブジェクトをセルに文字列化できますが、コンシューマーはそのセルを解析することを知っていなければなりません — 問題をただ移動させただけです。CSVにはネイティブの型システムもありません：trueは 文字列、42は文字列、nullは曖昧です。ツールはこれを 一貫性なく処理します。
  • TOONはLLMコンテキスト外で失敗します。これはより狭いエコシステムを持つニッチな形式です。 PostgreSQL、RESTフレームワーク、またはExcelにネイティブTOONサポートはありません。 npmパッケージは JavaScript/TypeScriptワークフローをよくカバーしますが、AIと関係のないコンテキストでTOONを使っているなら、 おそらく過剰設計しています。
  • CSVはカンマや改行を含む値で失敗します。RFC 4180のクォートルールが これを処理しますが、多くのCSVプロデューサーとコンシューマーは一貫性なく実装しています。 27" IPS Monitor, Blackのような製品名や改行を含む説明は 信頼性リスクになります。

意思決定マトリックス

実用的なガイドです。状況に応じて適切な形式を選んでください：

  • データがLLMプロンプトに入る → TOON。 特に表形式の場合。API呼び出し前にJSON to TOONを使って変換。
  • データがLLMから返ってきて処理が必要 → TOON （出力用）、その後TOON to JSONでJSONまたはネイティブオブジェクトにデコード。
  • データが純粋にフラットな表形式（各行に同じキー）でスプレッドシートとやり取りする → CSV。最も小さく普遍的にインポートできる表現です。
  • データはフラットな表形式だがコード（スプレッドシートではない）で変換される → CSVまたはJSON。型が重要な場合はJSONの方が安全（trueではなく"true"になりたくない）。
  • データにネストされたオブジェクトや配列がある → JSON。CSVの フラットのみの制限と戦わないでください。ネストがLLMに行く場合、構造を構築後にTOONにエンコード。
  • データがREST APIに行くか、データベースに保存される → JSON。 常に。
  • データが設定ファイル → JSONまたはYAML。 CSVもTOONもここには属しません。
  • 最大の移植性とゼロ依存パーサーが必要 → JSON またはCSV。どちらもほぼどこでもネイティブまたはネイティブに近いサポートがあります。

1つのパイプラインで3つすべてを使う

現実的なパイプラインでは3つすべてを使う場合があります。AI生成の説明で製品データを 豊かにするeコマースワークフローを想像してください：

ts
import { encode, decode } from '@toon-format/toon';

// Step 1: Products arrive as JSON from your REST API
const products = await fetch('/api/products').then(r => r.json());

// Step 2: Encode to TOON to minimise tokens before the LLM call
const toonInput = encode(products);

const response = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [
    {
      role: 'user',
      content: `Here is our product catalogue in TOON format:\n\n${toonInput}\n\n
                For each product, write a one-sentence marketing description.
                Return results as TOON with fields: id, description`
    }
  ]
});

// Step 3: Decode the LLM's TOON response back to objects
const enriched = decode(response.choices[0].message.content);

// Step 4: Export to CSV for the marketing team's spreadsheet
const csvRows = enriched.map(row => `${row.id},"${row.description}"`);
const csv = ['id,description', ...csvRows].join('\n');

API層にはJSON、LLM層を通じてはTOON、人間が消費できる出力にはCSV。 各形式は設計された仕事をまさにこなしています。

クイックツールリファレンス

これらの形式間を移動する場合、これらのツールが一般的な変換をカバーします。 TOONフォーマッターはTOON文字列を検証してクリーンアップする最速の方法です。 JSON to TOONコンバーターはLLM準備ステップを処理します。 LLMがTOONを返した後の逆方向では、TOON to CSVで スプレッドシート対応のエクスポートを直接生成でき、CSV to JSONは ExcelやサードパーティのデータプロバイダーからのインポートをNormalizationするための定番です。 TOON固有の詳細については、公式パッケージは npmにあります。

まとめ

JSON、CSV、TOONはそれぞれ明確な領域を持っています。JSONは構造化データ交換の普遍的な形式です — ネストまたはフラット、API、設定、ストレージ。CSVはシステムと人間の間を移動する必要があるフラットな表形式データの 普遍的な形式です — スプレッドシート、インポート、エクスポート。TOONは各トークンが重要な AIシステムを通じて効率的に構造化データを渡すための形式です。 ほとんどの開発者が犯す間違いは、LLMプロンプトを含むすべてにJSONをデフォルトにすること、または CSVをデフォルトにしてプロジェクトの途中でネスト要件を発見することです。データの形状を知り、 どこに行くのかを知れば、正しい形式はたいてい自ら選ばれます。

特にJSON対TOONのトレードオフについてさらに詳しく知りたい場合は、 TOON vs JSON比較をご覧ください。CSVの仕様と その癖については、 CSVに関するWikipedia記事が 歴史と形式のバリエーションをよくカバーしています。

← All TOON articles Browse all categories →