面向标记的对象表示法 (TOON)

面向标记的对象表示法 是 JSON 数据模型的一种紧凑、易读的编码方式，它将标记最小化，使模型易于理解结构。

TOON 将 YAML 的缩进结构用于嵌套对象，结合 CSV 风格的表格形式处理统一数据。它的理想应用场景是统一对象——无论是数组内还是由 ID 索引的每个条目字段相同——实现类似 CSV 的紧凑性，同时增加明确结构，帮助大语言模型可靠解析和验证数据。对于深层嵌套或非统一数据，JSON 可能更高效。

可以将其视为一个翻译层：以编程方式使用 JSON，然后将其编码为 TOON 以供 LLM 输入——这是对已有 JSON 的无损替代表示。

[!提示]
TOON 格式已经稳定，但仍在发展中。没有任何规定是固定不变的——可以通过贡献 规范 或提供反馈来帮助塑造其未来。

为什么选择 TOON？

LLM 的标记是有成本的——而 JSON 在结构上消耗大量标记。用 TOON 表示的天气预报：

location:
  city: Berlin
  country: DE
  units: metric
alerts[2]: frost,wind
forecast[3]{day,temp{min,max},condition,rainChance}:
  Mon,-2,4,snow,80
  Tue,1,7,cloudy,20
  Wed,3,11,sunny,5

相同的数据以 JSON 格式 – 大约 117 个标记，而 TOON 的大约 66 个：

{
  "location": {
    "city": "Berlin",
    "country": "DE",
    "units": "metric"
  },
  "alerts": [
    "frost",
    "wind"
  ],
  "forecast": [
    {
      "day": "Mon",
      "temp": {
        "min": -2,
        "max": 4
      },
      "condition": "snow",
      "rainChance": 80
    },
    {
      "day": "Tue",
      "temp": {
        "min": 1,
        "max": 7
      },
      "condition": "cloudy",
      "rainChance": 20
    },
    {
      "day": "Wed",
      "temp": {
        "min": 3,
        "max": 11
      },
      "condition": "sunny",
      "rainChance": 5
    }
  ]
}

在上面的 TOON 中，同时发生了三件事。其中两个是 表单 —— 一个是值的呈现，从数据的形状中自动选择 —— 第三个是标题功能：

• alerts[2]: frost,wind 是 内联表单：在其标题行上的原始数组。
• forecast[3]{day,…}: 是 表格表单：字段列表在标题中声明一次，然后每个元素一行。
• 该标题内的 temp{min,max} 是 嵌套字段组：统一的嵌套 temp 对象折叠到标题中，而行保持扁平。

第三种表单是 键控表格，用于值为统一对象的对象 —— 配置映射、功能标志、按 ID 的记录。长度后的冒号（[2:]）标记它，每行带有自己的键：

任何不符合上述任何一种情况的内容——混合类型、非统一对象——都会退回到第四种形式，列表形式：每个元素一个 - 项，或者空对象用单独的 -。这四种形式涵盖了结构；其余内容请参见 格式概览。

[!提示]
在你自己的数据上尝试——无需安装：

cat data.json | npx @toon-format/cli --stats

它会打印出 TOON 以及转换所节省的内容——在上面的天气预报中，那是：

ℹ 令牌估算：~117（JSON）→ ~66（TOON）
✔ 节省约51个令牌（-43.6%）

主要特性

• 📊 高效与准确的令牌使用: 在使用比 JSON 少 42.6% 的令牌的情况下，实现与 JSON 相同的检索准确性 – 见 基准测试。
• 🔁 JSON 数据模型: 编码与 JSON 相同的对象、数组和原始类型，支持确定性、无损的来回转换。
• 🛤️ LLM 友好的保护措施: [N] 声明行数，{fields} 声明字段宽度 – 因此截断或格式错误的输出无法通过。
• 📐 最简语法: 使用缩进代替大括号，并最小化引号的使用，提供类似 YAML 的可读性和 CSV 风格的紧凑性。
• 🧺 表格形式: 统一对象 – 在数组中或键下 – 声明字段列表一次，然后每次流式输出一行。
• 🌐 多语言生态系统: 官方实现及数十个社区移植版本，均遵循同一规范，并共享一致性测试套件。

何时不使用 TOON

TOON 擅长处理统一对象的数组。当出现以下情况时应选择其他方案：

• 结构深度嵌套或非统一（表格适用性 ≈ 0%）– 紧凑 JSON 往往直接获胜。
• 数组半统一 (~40–60% 适用性) – 节省的数量减少；如果你的流程已经支持 JSON，则继续使用 JSON。
• 数据完全表格化 – CSV 更小。TOON 的约 5–10% 开销换来已声明的长度、字段列表和分隔符作用域，这是可靠性权衡，而非大小权衡。
• 延迟主导 – 某些部署（特别是本地或量化模型）尽管令牌数量更多，但处理紧凑 JSON 更快。请在你自己的环境中测量 TTFT 和总时间。

基准测试 下文量化了令牌和准确性的权衡；延迟是需要你自己测量的。

基准测试

两条赛道，因此每次比较都是可比的：

• 混合结构赛道: 嵌套和半统一数据集（TOON 对比 JSON、YAML、XML）。CSV 被排除 – 它无法在不丢失的扁平化情况下表示这些结构。
• 仅扁平赛道: 扁平、完全表格化适用的数据集，CSV 是公平的竞争者。

检索准确性

基准测试通过在4个模型上使用244个数据检索问题来测试大型语言模型（LLM）对不同输入格式的理解能力。

效率排名（每千个标记的准确率）

按效率对每种格式进行排名（每 1,000 个标记的准确率百分比）

TOON           ████████████████████   29.2 acc%/1K tok  │  72.2%  ±2.8 acc  │  2,474 tokens
JSON compact   ████████████████░░░░   23.8 acc%/1K tok  │  69.0%  ±2.9 acc  │  2,892 tokens
YAML           ██████████████░░░░░░   20.1 acc%/1K tok  │  70.1%  ±2.9 acc  │  3,487 tokens
JSON           ███████████░░░░░░░░░   16.6 acc%/1K tok  │  71.4%  ±2.8 acc  │  4,308 tokens
XML            ██████████░░░░░░░░░░   14.4 acc%/1K tok  │  70.7%  ±2.9 acc  │  4,909 tokens

效率评分 = (准确率 % ÷ 令牌) × 1,000。数值越高越好。

[!提示]
TOON 达到 72.2% 的准确率（相比 JSON 的 71.4%），同时使用的令牌 少 42.6%。

[!注意]
CSV 被排除在排名之外，因为它仅支持 244 个问题中的 109 个（仅平面表格数据）。虽然 CSV 对简单表格数据的令牌使用效率很高，但它无法表示其他格式可以处理的嵌套结构。

平面数据集的准确率

每种格式都对每个模型回答相同的 109 个平面数据集问题，因此可以在这里将 CSV 公平地进行比较。

按模型准确率

在 244 个数据检索问题上的 4 个大型语言模型的准确率：

claude-haiku-4-5-20251001
→ TOON           █████████████░░░░░░░    65.6% ±5.9 (160/244)
  JSON           █████████████░░░░░░░    63.5% ±6.0 (155/244)
  XML            ████████████░░░░░░░░    62.3% ±6.0 (152/244)
  YAML           ████████████░░░░░░░░    62.3% ±6.0 (152/244)
  JSON compact   ████████████░░░░░░░░    61.9% ±6.0 (151/244)
  CSV            ██████████░░░░░░░░░░    49.5% ±9.2 (54/109)

gemini-3.6-flash
→ TOON           ██████████████░░░░░░    69.3% ±5.8 (169/244)
  JSON           ██████████████░░░░░░    68.4% ±5.8 (167/244)
  YAML           ██████████████░░░░░░    67.6% ±5.8 (165/244)
  XML            █████████████░░░░░░░    65.2% ±5.9 (159/244)
  JSON compact   █████████████░░░░░░░    63.5% ±6.0 (155/244)
  CSV            ████████████░░░░░░░░    57.8% ±9.1 (63/109)

gpt-5.4-nano
  XML            ████████████░░░░░░░░    59.4% ±6.1 (145/244)
  JSON           ███████████░░░░░░░░░    57.4% ±6.2 (140/244)
→ TOON           ███████████░░░░░░░░░    57.0% ±6.2 (139/244)
  JSON compact   ███████████░░░░░░░░░    54.9% ±6.2 (134/244)
  YAML           ███████████░░░░░░░░░    54.5% ±6.2 (133/244)
  CSV            █████████░░░░░░░░░░░    46.8% ±9.2 (51/109)

grok-4.5
→ TOON           ███████████████████░    97.1% ±2.2 (237/244)
  JSON           ███████████████████░    96.3% ±2.5 (235/244)
  XML            ███████████████████░    95.9% ±2.6 (234/244)
  YAML           ███████████████████░    95.9% ±2.6 (234/244)
  JSON compact   ███████████████████░    95.5% ±2.7 (233/244)
  CSV            ███████████████████░    94.5% ±4.5 (103/109)

[!注意]
准确性数字包括 Wilson 95% 置信区间（±）；当两种格式的区间重叠时，它们之间的差异在统计上没有意义。CSV 答案只包含 109 个平面数据集问题，因此其每个模型的单元格覆盖的人群较小且更容易，相较于其他格式。

运行配置

• 测试模型：claude-haiku-4-5-20251001、gemini-3.6-flash、gpt-5.4-nano、grok-4.5
• 比较格式：TOON、JSON、XML、YAML、紧凑JSON、CSV
• 令牌计数：使用 gpt-tokenizer 的 o200k_base 编码（GPT-5 分词器）。其他提供商的分词方式不同，因此绝对计数取决于分词器；格式之间的相对差异方向一致。
• 推理：通过 AI SDK 的通用 reasoning: 'none' 禁用（Gemini 3 以最小思考运行，grok-4.5 设置为 low）
• 温度：未设置（模型使用默认值）
• 总评估：244 个问题 × 6 种格式 × 4 个模型 = 5,856 次 LLM 调用

数据集包含的内容、问题生成方式以及答案验证方式已在基准测试 README中记录。

令牌效率

令牌计数是使用 GPT-5 o200k_base 分词器通过 gpt-tokenizer 测量的。节省量是以格式化的 JSON（2 空格缩进）为主要基准计算的，同时也与紧凑 JSON（最小化）、YAML 和 XML 进行了额外比较。实际节省量因模型和分词器而异。

基准测试的数据集涵盖不同结构模式（均匀、半均匀、嵌套、深度嵌套），以显示 TOON 的优势所在以及其他格式可能更好的场景。

混合结构跟踪

具有嵌套或半统一结构的数据集。排除 CSV，因为它无法正确表示这些结构。

🛒 E-commerce orders with nested structures  ┊  Tabular: 33%
   │
   TOON                █████████████░░░░░░░    72,832 tokens
   ├─ vs JSON          (−32.9%)               108,611 tokens
   ├─ vs JSON compact  (+5.6%)                 68,944 tokens
   ├─ vs YAML          (−14.0%)                84,701 tokens
   └─ vs XML           (−40.4%)               122,119 tokens

🧾 Semi-uniform event logs  ┊  Tabular: 50%
   │
   TOON                █████████████████░░░   154,084 tokens
   ├─ vs JSON          (−15.0%)               181,201 tokens
   ├─ vs JSON compact  (+19.9%)               128,529 tokens
   ├─ vs YAML          (−0.8%)                155,397 tokens
   └─ vs XML           (−25.2%)               205,859 tokens

🧩 Deeply nested configuration  ┊  Tabular: 0%
   │
   TOON                █████████████░░░░░░░       589 tokens
   ├─ vs JSON          (−34.9%)                   905 tokens
   ├─ vs JSON compact  (+6.7%)                    552 tokens
   ├─ vs YAML          (−11.0%)                   662 tokens
   └─ vs XML           (−40.9%)                   997 tokens

📊 Feature flags keyed by name  ┊  Tabular: 100%
   │
   TOON                █████████░░░░░░░░░░░    10,503 tokens
   ├─ vs JSON          (−54.6%)                23,141 tokens
   ├─ vs JSON compact  (−32.8%)                15,635 tokens
   ├─ vs YAML          (−41.3%)                17,905 tokens
   └─ vs XML           (−63.3%)                28,655 tokens

📊 Contacts with nested address and plan groups  ┊  Tabular: 100%
   │
   TOON                ███████░░░░░░░░░░░░░    26,726 tokens
   ├─ vs JSON          (−66.5%)                79,779 tokens
   ├─ vs JSON compact  (−42.9%)                46,791 tokens
   ├─ vs YAML          (−51.8%)                55,475 tokens
   └─ vs XML           (−70.4%)                90,306 tokens

──────────────────────────────────── Total ────────────────────────────────────
   TOON                █████████████░░░░░░░   264,734 tokens
   ├─ vs JSON          (−32.7%)               393,637 tokens
   ├─ vs JSON compact  (+1.6%)                260,451 tokens
   ├─ vs YAML          (−15.7%)               314,140 tokens
   └─ vs XML           (−40.9%)               447,936 tokens

仅平面轨道

具有平面、完全可用于表格的数据集，适用于 CSV。

👥 Uniform employee records  ┊  Tabular: 100%
   │
   CSV                 ███████████████████░    47,153 tokens
   TOON                ████████████████████    49,978 tokens   (+6.0% vs CSV)
   ├─ vs JSON          (−60.7%)               127,061 tokens
   ├─ vs JSON compact  (−36.8%)                79,057 tokens
   ├─ vs YAML          (−50.0%)               100,054 tokens
   └─ vs XML           (−65.9%)               146,605 tokens

📈 Time-series analytics data  ┊  Tabular: 100%
   │
   CSV                 ██████████████████░░     8,383 tokens
   TOON                ████████████████████     9,115 tokens   (+8.7% vs CSV)
   ├─ vs JSON          (−59.0%)                22,245 tokens
   ├─ vs JSON compact  (−35.9%)                14,211 tokens
   ├─ vs YAML          (−49.0%)                17,858 tokens
   └─ vs XML           (−65.8%)                26,616 tokens

⭐ Top 100 GitHub repositories  ┊  Tabular: 100%
   │
   CSV                 ███████████████████░     8,711 tokens
   TOON                ████████████████████     8,937 tokens   (+2.6% vs CSV)
   ├─ vs JSON          (−41.7%)                15,337 tokens
   ├─ vs JSON compact  (−23.2%)                11,640 tokens
   ├─ vs YAML          (−33.0%)                13,337 tokens
   └─ vs XML           (−48.3%)                17,294 tokens

──────────────────────────────────── Total ────────────────────────────────────
   CSV                 ███████████████████░    64,247 tokens
   TOON                ████████████████████    68,030 tokens   (+5.9% vs CSV)
   ├─ vs JSON          (−58.7%)               164,643 tokens
   ├─ vs JSON compact  (−35.2%)               104,908 tokens
   ├─ vs YAML          (−48.2%)               131,249 tokens
   └─ vs XML           (−64.3%)               190,515 tokens

令牌计数使用 gpt-tokenizer 并采用 o200k_base 编码（GPT-5 分词器）。其他提供商的分词方式不同，因此绝对计数取决于分词器；不同格式之间的相对差异在方向上保持一致。

{
  "指标": ["
    {
      "date": "2025-01-01",
      "views": 6138,
      "clicks": 174,
      "conversions": 12,
      "revenue": 2712.49,
      "bounceRate": 0.35
    },
    {
      "date": "2025-01-02",
      "views": 4616,
      "clicks": 274,
      "conversions": 34,
      "revenue": 9156.29,
      "bounceRate": 0.56
    },
    {
      "date": "2025-01-03",
      "views": 4460,
      "clicks": 143,
      "conversions": 8,
      "revenue": 1317.98,
      "bounceRate": 0.59
    },
    {
      "date": "2025-01-04",
      "views": 4740,
      "clicks": 125,
      "conversions": 13,
      "revenue": 2934.77,
      "bounceRate": 0.37
    },
    {
      "date": "2025-01-05",
      "views": 6428,
      "clicks": 369,
      "conversions": 19,
      "revenue": 1317.24,
      "bounceRate": 0.3
    }
  ]
}

metrics[5]{日期,浏览量,点击量,转化,收入,跳出率}:
  2025-01-01,6138,174,12,2712.49,0.35
  2025-01-02,4616,274,34,9156.29,0.56
  2025-01-03,4460,143,8,1317.98,0.59
  2025-01-04,4740,125,13,2934.77,0.37
  2025-01-05,6428,369,19,1317.24,0.3

{
  "repositories": ["
    {
      "id": 132750724,
      "name": "build-your-own-x",
      "repo": "codecrafters-io/build-your-own-x",
      "description": "Master programming by recreating your favorite technologies from scratch.",
      "createdAt": "2018-05-09T12:03:18Z",
      "updatedAt": "2026-07-23T18:57:15Z",
      "pushedAt": "2026-07-14T19:25:58Z",
      "stars": 530712,
      "watchers": 6778,
      "forks": 50205,
      "defaultBranch": "master"
    },
    {
      "id": 21737465,
      "name": "awesome",
      "repo": "sindresorhus/awesome",
      "description": "😎 Awesome lists about all kinds of interesting topics",
      "createdAt": "2014-07-11T13:42:37Z",
      "updatedAt": "2026-07-23T18:57:24Z",
      "pushedAt": "2026-06-30T18:21:16Z",
      "stars": 488074,
      "watchers": 8292,
      "forks": 36010,
      "defaultBranch": "main"
    },
    {
      "id": 28457823,
      "name": "freeCodeCamp",
      "repo": "freeCodeCamp/freeCodeCamp",
      "description": "freeCodeCamp.org's open-source codebase and curriculum. Learn math, programming,…",
      "createdAt": "2014-12-24T17:49:19Z",
      "updatedAt": "2026-07-22T07:01:33Z",
      "pushedAt": "2026-07-21T18:00:51Z",
      "stars": 452380,
      "watchers": 8590,
      "forks": 45624,
      "defaultBranch": "main"
    }
  ]
}

repositories[3]{id,名称,仓库,描述,创建时间,更新时间,推送时间,收藏数,关注者,分支数,默认分支}:
  132750724，build-your-own-x，codecrafters-io/build-your-own-x，通过从零开始重现你喜欢的技术来掌握编程。“2018-05-09T12：03：18Z”，“2026-07-23T18：57：15Z”，“2026-07-14T19：25：58Z”，530712,6778,50205，master。
  21737465，awesome，sindresorhus/awesome，😎关于各种有趣话题的精彩列表，“2014-07-11T13：42：37Z”，“2026-07-23T18：57：24Z”，“2026-06-30T18：21：16Z”，488074,8292,36010，主线
  28457823，freeCodeCamp，freeCodeCamp/freeCodeCamp，“freeCodeCamp.org的开源代码库和课程。学习数学，编程,...”，“2014-12-24T17：49：19Z”，“2026-07-22T07：01：33Z”，“2026-07-21T18：00：51Z”，452380,8590,45624，main”

安装与快速开始

# npm
npm install @toon-format/toon

# pnpm
pnpm add @toon-format/toon

# yarn
yarn add @toon-format/toon

如果想保留 CLI 而不是通过 npx 调用它，请全局安装它：

npm install -g @toon-format/cli

示例用法：

import { encode } from '@toon-format/toon'

const data = {
  users: [
    { id: 1, name: 'Ada', role: 'admin' },
    { id: 2, name: 'Bob', role: 'user' }
  ]
}

console.log(encode(data))
// users[2]{id,name,role}:
//   1,Ada,admin
//   2,Bob,user

流式传输大数据集：

import { encodeLines } from '@toon-format/toon'

const largeData = await fetchThousandsOfRecords()

// Memory-efficient streaming for large data
for (const line of encodeLines(largeData)) {
  process.stdout.write(`${line}\n`)
}

[!提示]
有关流解码 API，请参阅 decodeFromLines() 和 decodeStream()。

使用替换器转换值：

import { encode } from '@toon-format/toon'

README 内容已截断, 请前往 GitHub 查看完整内容。