Skip to content
json2toon.co
ConvertDocsAPIBlog
Open source
ConvertDocsAPIBlogGitHub
Home/Format comparison/JSON to TOON migration

JSON to TOON migration guide: 6 steps

Updated 2026-11-17 by json2toon.co

Migrating from JSON to TOON does not mean replacing JSON. Keep JSON in your APIs, database and model outputs, and encode to TOON at the last step before data enters a prompt. Measure the saving on your real payloads first, convert with a library, the REST API or the MCP server, and verify the round trip before you roll it out.

Step 1: measure your payload →Find a TOON library →

Token counts on the same data

Sample dataJSONJSON (minified)TOON
GitHub issues: Flat uniform array: 8 records, 7 fields each587388 (-34%)294 (-50%)
Stripe charges list: Object wrapping a uniform array: 7 records, 7 fields each512335 (-35%)246 (-52%)
Nested orders: 3 records, each with a nested customer object and an items array219122 (-44%)146 (-33%)
Kubernetes Deployment: Deeply nested config, no uniform arrays230119 (-48%)132 (-43%)
Tokens counted with o200k_base (GPT-4o and GPT-5 family); percentages are relative to JSON. Every output was produced by this site's converter (@toon-format/toon 4.4.0, tonl 2.5.2). These are small samples taken from the converter's built-in examples and conversion pages, not a benchmark: measure your own payload in the TOON token calculator.

Step 1: Measure before you change anything

Savings depend on the shape of your data, as the table above shows: large on uniform arrays, small or negative on nested objects when you already minify. Paste a real payload into the TOON token calculator to see JSON, minified JSON, TOON and TONL token counts and the cost per million calls. If the difference is small, stop here and minify your JSON instead.

Step 2: Decide where to encode

Encode at one boundary: the function that builds the prompt. Storage, APIs and business logic stay in JSON. Good first candidates are large and repetitive inputs such as SQL results, REST API responses, vector search results and logs.

Step 3: Convert with a library, the API or MCP

In TypeScript or JavaScript, with the official @toon-format/toon package:

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

const prompt = `Answer using this data:\n${encode(rows)}`;

In Python, with toon_format:

from toon_format import encode, decode

prompt = f"Answer using this data:\n{encode(rows)}"

Install guides for these and other languages are under TOON libraries by language. If you cannot add a dependency, the free TOON API converts over HTTP with no key:

curl -X POST https://json2toon.co/api/v1/toon \
  -H "Content-Type: application/json" \
  -d '{"content": "{\"users\":[{\"id\":1,\"name\":\"Ann\"}]}", "format": "json"}'

Agents and chat clients can call the TOON MCP server (json_to_toon and toon_to_json), and for one-off conversions there is the JSON to TOON converter and the Chrome extension.

Step 4: Keep model output in JSON

Change what the model reads, not what it writes. An independent arXiv study (2603.03306) found plain JSON gave the best accuracy for generated structured output, and "Notation Matters" (arXiv 2605.29676) found that having models write tool calls in a compact format broke parallel calls for most models tested. Leave structured outputs and tool calls as JSON. TOON for function calling shows the split in practice.

Step 5: Verify the round trip

TOON is lossless, so the cheapest test is to decode what you encoded and compare it with the input:

import assert from 'node:assert';
assert.deepStrictEqual(decode(encode(rows)), rows);

Run it over a sample of production payloads. Validate the JSON itself before encoding, for example with the JSON Schema validator, and repair malformed input with JSON repair. Validating TOON data has more checks.

Step 6: Roll out and compare

Ship it behind a flag for one prompt, then compare input tokens and answer quality against the JSON version on the same requests. The official benchmark found retrieval accuracy on par with JSON, but your model and task are what count. Rolling back is removing one encode() call. For common mistakes, see TOON best practices and troubleshooting.

Try it on your data

Everything runs in your browser, so nothing you paste is uploaded. Convert a real payload, then check the token counts side by side before you decide.

Step 1: measure your payload →Find a TOON library →

Frequently asked questions

Do I need to change my database or API to use TOON?

No. Keep JSON in storage and APIs and encode to TOON only where data is placed into a prompt. TOON is a translation layer for model input, not a replacement for JSON.

Is JSON to TOON conversion lossless?

Yes. Decoding TOON returns the same values, types and key order as the JSON it was encoded from, so you can verify a migration by comparing decode(encode(data)) with the original.

How do I convert JSON to TOON in code?

Install a TOON library for your language, such as @toon-format/toon from npm or toon_format from pip, and call encode() on your data. Without a library, POST the JSON to the free API at json2toon.co/api/v1/toon.

Should the model respond in TOON after I migrate?

No. Keep structured outputs and tool calls in JSON. Research on generation (arXiv 2603.03306) found plain JSON more accurate for model output; TOON is for the data the model reads.

How much will I save by migrating?

TOON uses about 43% fewer tokens than JSON on average (42.6% in the official TOON v4.1 benchmark), more on flat uniform tables and much less on nested or irregular data. Measure your own payloads in the token calculator before committing.

Keep reading

  • TOON best practices and troubleshooting
  • TOON in Python and JavaScript
  • Migrating to TOON v4
  • LLM optimization use case

More comparisons

  • TOON vs JSON vs YAML: all formats compared
  • TOON vs JSON
  • TOON vs TONL
  • TOON vs YAML
  • TOON vs CSV
  • TOON alternatives
Privacy-first web converter. Browser-based conversions keep source data on your device.

Product

  • JSON Tools
  • Convert
  • Token Calculator
  • TOON API
  • MCP Server
  • Chrome Extension

Resources

  • TOON vs JSON, YAML, CSV
  • TOON Alternatives
  • FAQ
  • Use Cases
  • TOON Libraries
  • Changelog
  • LLMs.txt

Project

  • About
  • Contact
  • Privacy
  • Terms
  • GitHub
  • Report Bug

© 2026 json2toon.co

Listed on dofollow.tools