The Problem
Large Language Models consume JSON as a primary data interchange format, but JSON is token-expensive. A typical array of 100 objects with 10 fields each can consume thousands of tokens just for structural syntax ({, }, ", ,). As context windows grow and token costs accumulate, this verbosity directly impacts operational cost and response latency. TOON addresses this by providing a lossless, more compact encoding of the JSON data model specifically optimized for LLM input.
What This Does
TOON combines YAML-style indentation for nested objects with CSV-style tabular layout for uniform arrays. The core implementation lives in packages/toon/src/ with separate encode/ and decode/ modules. The encoder (encoders.ts, folding.ts, normalize.ts) handles JSON-to-TOON conversion, while the decoder (parser.ts, scanner.ts, validation.ts) handles the reverse. A streaming decoder (decodeStream.ts) supports incremental parsing.
The repo includes a CLI (packages/cli/src/index.ts) for file conversion, a benchmark suite (benchmarks/scripts/) with published results in benchmarks/results/, and comprehensive documentation (docs/guide/, docs/reference/). The spec is maintained separately at toon-format/spec.
How To Use It
Setup: Install via pnpm (the workspace uses pnpm-workspace.yaml):
pnpm install
Configuration: No environment variables are required for basic usage. The benchmark suite uses benchmarks/.env.example for API keys if you want to run accuracy benchmarks against LLM providers.
Running it: Import the library directly:
import { encode, decode } from '@toon-format/toon';
const json = { users: [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }] }; const toon = encode(json); const back = decode(toon);
Or use the CLI: pnpm --filter @toon-format/cli run toon --input data.json --output data.toon
Real-World Use
A typical pattern: your backend produces JSON from a database query, you encode it as TOON before sending to an LLM, and the model can parse it with fewer tokens and higher accuracy. The benchmark results (benchmarks/results/token-efficiency.md) show this achieves meaningful token savings on uniform array data—the common case for tabular data like logs, events, or product catalogs.
Code Health & Issues
Med - Forked repo, original has 25k+ stars: This is a fork of toon-format/toon. Verify the fork is current with upstream before adopting. Low - No license in fork: The LICENSE file exists but verify it matches the upstream MIT license. Low - Benchmark results may be stale: Results files are committed but there's no indication of when they were last run. Check dates before citing them. Med - CLI lacks comprehensive tests: packages/cli/test/ covers core conversion but not all edge cases (e.g., malformed input handling).
The codebase is cleanly structured with separate encode/decode modules, validation logic (validation.ts), and a well-organized test suite (packages/toon/test/). CI is configured via GitHub Actions.
The Bottom Line
TOON is a legitimate solution to a real cost problem: token efficiency for structured data in LLM prompts. The implementation is clean, well-tested, and the benchmark methodology is documented. It's most valuable for teams processing large uniform datasets through LLMs—if your data is deeply nested or highly irregular, JSON may remain more efficient. The fork status is the primary concern; verify it tracks upstream before building on it.