JSON to TOON Converter Documentation

Tool Overview

The JSON to TOON Converter is a 100% client-side web application that transforms standard JSON data into token-optimized TOON format. It provides real-time token analysis, cost calculations, and conversion history tracking—all without sending your data to any server.

Key Capabilities

Instant Conversion

Real-time JSON to TOON transformation with auto-convert on input

Token Analysis

Estimate token counts and calculate cost savings for LLM APIs

History Tracking

Save and review up to 50 recent conversions locally

Customizable

Configure delimiters, indentation, and formatting options

Getting Started

Quick Start (30 seconds)

1

Open the converter

Navigate to the JSON to TOON Converter homepage
2

Paste your JSON

Copy your JSON data and paste it into the left input panel, or drag & drop a .json file
3

Convert

Click the "Convert to TOON" button or wait for auto-convert (triggers after 500ms of inactivity)
4

Copy or download

Use the Copy button to paste into your LLM prompt, or download as a .toon file

✓ That's it!

Your TOON output appears on the right with token analysis showing exactly how many tokens you saved.

Features in Detail

🔄 Real-Time Auto-Convert

The converter automatically processes your JSON as you type, with a 500ms debounce delay to avoid excessive processing:

Type or paste JSON in the input field
Wait 500ms (half a second)
Conversion happens automatically
No need to click "Convert" unless you prefer manual control

📝 Example Data Loader

Click the "Example" button to cycle through pre-loaded sample datasets:

• User Records (3 entries)
• Product Catalog (4 items)
• API Response (GitHub-style)

Perfect for testing the converter or learning TOON format with realistic data.

🌓 Dark/Light Mode

Toggle between dark and light themes using the moon/sun icon in the header. The converter remembers your preference using browser localStorage.

Input Methods

Method 1: Copy & Paste

The simplest method:

1. Copy JSON from your source (API response, file, etc.)
2. Click in the input textarea
3. Paste (Ctrl+V / Cmd+V)
4. Conversion happens automatically

Method 2: Drag & Drop Files

Fastest for local .json files:

1. Open your file explorer/finder
2. Drag a .json file over the input area
3. Drop when you see the blue overlay
4. File contents are loaded and converted automatically

Note: Only .json files are accepted. Other file types will show an error message.

Method 3: Load Examples

Perfect for learning and testing:

1. Click the "📝 Example" button in the input panel header
2. Cycles through pre-loaded sample datasets
3. Each click loads the next example
4. Great for understanding TOON format with real data

Configuration Options

Delimiter Selection

Choose the separator for tabular data rows:

Delimiter	Character	Best For
Comma (default)	`,`	Most use cases, standard CSV format
Tab	`\t`	Data with many commas in values
Pipe	`\|`	Data with commas and tabs

💡 Tip: Comma is recommended for most scenarios. Change only if your data values contain many commas.

Indentation Style

Controls how nested objects are indented:

2 Spaces

Compact, saves more tokens

parent:child: value

4 Spaces (default)

Balance of readability & efficiency

parent:
child: value

Tab

Traditional, uses single character

parent:
child: value

Length Markers

Toggle to show/hide array lengths like [100]:

✓ Enabled (default)

users[3]{id,name}:
1,Alice
2,Bob
3,Charlie

Helps LLMs validate data completeness

Disabled

users{id,name}:
1,Alice
2,Bob
3,Charlie

Saves 1-3 tokens per array

Recommendation: Keep enabled. The validation benefits outweigh the minimal token cost.

Token Price Configuration

Set your LLM API's token price ($ per 1,000 tokens) for accurate cost calculations:

Common Pricing (as of 2025):

• GPT-4 Turbo: $0.01 per 1K tokens (input)
• GPT-3.5 Turbo: $0.0005 per 1K tokens
• Claude 3 Opus: $0.015 per 1K tokens
• Claude 3 Sonnet: $0.003 per 1K tokens
• Gemini Pro: $0.00025 per 1K tokens

Default is 0.0025 - adjust based on your provider and model.

Save/Load Configuration

Persist your settings across sessions:

Save Config

Stores delimiter, indent, length markers, and token price to browser localStorage

Load Config

Restores your saved settings - auto-loads on page refresh

Understanding Token Analysis

After conversion, the tool displays detailed token metrics to help you understand the optimization impact:

📊 Metrics Explained

JSON Tokens

Estimated token count for your original JSON input

TOON Tokens

Estimated token count for the converted TOON output

Tokens Saved

Difference between JSON and TOON (higher is better)

Reduction %

Percentage of tokens saved (typically 30-60%)

Cost Saved

Estimated API cost savings based on your configured token price

Token Estimation Method

The converter uses a heuristic-based estimation combining:

• Character count method: Approximately 4 characters per token
• Word count method: Words × 1.3 token multiplier
• Averaged result: Mean of both methods for accuracy

Accuracy Note: Token estimation is approximately 85-95% accurate. Different LLM providers use different tokenizers (OpenAI's tiktoken, Claude's tokenizer, etc.). However, the relative savings (JSON vs TOON) remain consistent across all tokenizers.

Real-World Example

Conversion Result:

JSON Input

342 tokens

TOON Output

156 tokens

Saved

186 tokens (54%)

Cost Saved (@ $0.01/1K)

$0.00186

For 1,000 similar API calls per day, you'd save $1.86/day or ~$56/month!

Conversion History

The converter automatically saves your last 50 conversions to browser localStorage, allowing you to review and reload previous conversions.

Accessing History

1 Click the clock icon (🕒) in the top-right header
2 History modal opens showing all saved conversions
3 Click "Load" on any entry to restore that conversion

What's Saved

📋 Conversion Data

• Original JSON input
• Converted TOON output
• Timestamp of conversion

📊 Metrics

• JSON token count
• TOON token count
• Tokens saved & percentage

Managing History

Automatic Limit

History is capped at 50 entries. Oldest conversions are automatically removed when the limit is reached.

Clear History

Click "Clear History" button in the history modal to delete all saved conversions.

Badge Counter

The history icon shows a badge with the number of saved conversions.

🔒 Privacy: All history data is stored locally in your browser. It never leaves your device and is automatically deleted if you clear browser data.

Export & Usage

📋 Copy to Clipboard

The fastest way to use your TOON output in LLM prompts:

1. Click the "📋 Copy" button in the output panel
2. TOON text is copied to your clipboard
3. Paste directly into ChatGPT, Claude, or any LLM interface
4. Success notification confirms the copy

✓ Recommended: Add context in your prompt like "Here's user data in TOON format:" to help the LLM parse correctly.

💾 Download as File

Save TOON output as a .toon file for later use:

1. Click the "💾 Download" button
2. File downloads as output.toon
3. Store for documentation or batch processing
4. Can be opened in any text editor

Use cases: Archiving conversions, sharing with team members, version control, or integrating into automated workflows.

🚀 Integration Example

How to use TOON in an actual LLM prompt:

You are analyzing user activity data. Here's the data in TOON format:activity[5]{user_id,action,timestamp,duration}:
101,login,2025-01-15T09:00:00,2
101,view_dashboard,2025-01-15T09:02:00,45
102,login,2025-01-15T09:05:00,3
102,search,2025-01-15T09:08:00,12
101,logout,2025-01-15T09:47:00,1
Please summarize user behavior patterns and identify the most active user.

This saves ~40% tokens compared to sending the same data as JSON!

Troubleshooting

❌ "Invalid JSON" Error

Problem: You see an error message when pasting or typing JSON.

Common Causes:

• Trailing commas: {"name": "Alice",}
• Single quotes instead of double: {'name': 'Alice'}
• Comments in JSON: // This is not allowed
• Missing quotes around keys: {name: "Alice"}
• Unescaped special characters in strings

Solution: Use a JSON validator (like jsonlint.com) to fix your JSON before pasting.

⚠️ Auto-Convert Not Working

Problem: Nothing happens after pasting JSON.

Solution:

• Wait 500ms (half a second) for debounce delay
• Manually click the "Convert to TOON" button
• Check browser console for JavaScript errors (F12)
• Refresh the page if the tool is unresponsive

ℹ️ Token Savings Lower Than Expected

Problem: Showing only 10-20% savings instead of 30-60%.

Possible Reasons:

• Non-uniform data: Objects in arrays have different keys
• Deeply nested structure: 5+ levels of nesting
• Small dataset: Only 1-5 items in array
• Mixed types: Array contains both objects and primitives

Solution: TOON works best with uniform arrays of 10+ objects. Consider normalizing your data or sticking with JSON for this use case.

🗑️ History Not Saving

Problem: Conversions don't appear in history.

Causes & Solutions:

• Private/Incognito mode: localStorage doesn't persist. Use normal browsing mode.
• Browser storage disabled: Check browser settings to enable cookies/storage.
• Storage quota exceeded: Clear browser data or delete old history entries.
• Invalid conversion: History only saves successful conversions, not errors.

📁 Drag & Drop Not Working

Problem: File drop doesn't load JSON.

Checklist:

• ✓ File has .json extension
• ✓ File contains valid JSON
• ✓ File size is reasonable (<10MB recommended)
• ✓ Dragging directly over the input textarea area
• ✓ Browser supports drag & drop (not IE11)

🐛 Still Having Issues?

If problems persist:

1. Clear browser cache: Ctrl+Shift+Delete (Windows) or Cmd+Shift+Delete (Mac)
2. Try a different browser: Chrome, Firefox, Safari, or Edge
3. Check browser console: Press F12 and look for error messages
4. Disable extensions: Ad blockers or privacy tools may interfere
5. Hard refresh: Ctrl+F5 (Windows) or Cmd+Shift+R (Mac)

Privacy & Security

🔒 100% Client-Side Processing

The JSON to TOON converter operates entirely in your browser. Your data never leaves your device.

What We DON'T Do

No Server Upload

Your JSON and TOON data is never transmitted to any server or third party
No Analytics Tracking

We don't use Google Analytics, Facebook Pixel, or any tracking scripts
No Cookies

No tracking cookies, session cookies, or third-party cookies are set
No Account Required

No login, no email collection, no personal information stored
No Logs

We don't log conversions, errors, or any user activity

What We DO Store (Locally)

The following data is stored in your browser's localStorage and never leaves your device:

Data	Purpose	Can Delete?
Theme preference	Remember dark/light mode	✓ Clear browser data
Configuration settings	Delimiter, indent, token price	✓ Clear browser data
Conversion history (last 50)	Review past conversions	✓ "Clear History" button

Security Best Practices

✓ Safe to Use

• Proprietary business data
• Customer information
• Internal analytics
• API responses

🔒 Open Source

All code is client-side JavaScript. View source to verify no data transmission occurs.

🛡️ Privacy Guarantee

We believe in privacy-first tools. Your data is yours. This converter is designed to never compromise that principle.

Questions about privacy? Inspect the browser's Network tab (F12 → Network) during conversion. You'll see zero outbound requests.

Quick Reference

⌨️ Keyboard Shortcuts

Ctrl/Cmd + V Paste JSON
Ctrl/Cmd + C Copy TOON (after focus)
F12 Open browser console