TOON

v1.1.5

Last updated Dec 10, 2025

n8n node for TOON (Token-Oriented Object Notation) format conversion - bidirectional conversion between TOON and JSON with zero external dependencies

208 Weekly Downloads

747 Monthly Downloads

View on NPM GitHub Repository

Included Nodes

TOON

Description

n8n-nodes-toon

This is an n8n community node that provides bidirectional conversion between TOON (Token-Oriented Object Notation) and JSON formats. TOON is a line-oriented, indentation-based format optimized for LLM prompts and structured data interchange.

n8n is a fair-code licensed workflow automation platform.

What is TOON?
Installation
Operations
Configuration Options
Usage Examples
Use Cases
Compatibility
Zero Dependencies
Resources

What is TOON?

TOON (Token-Oriented Object Notation) is a compact text format that encodes the JSON data model with explicit structure and minimal quoting. It's particularly efficient for arrays of uniform objects — common in data exports, API responses, and LLM prompts.

Key Features

Line-oriented and indentation-based — similar to YAML but more deterministic
Minimal quoting — strings are quoted only when necessary
Explicit array lengths — detect truncation and malformed data
Tabular arrays — declare field lists once, then list values row by row
Multiple delimiters — comma, tab, or pipe for different use cases
Zero external dependencies — pure Node.js implementation

Quick Example

JSON:

{
  "users": [
    {"id": 1, "name": "Alice", "role": "admin"},
    {"id": 2, "name": "Bob", "role": "user"}
  ]
}

TOON:

users[2]{id,name,role}:
  1,Alice,admin
  2,Bob,user

The TOON format is 50% more compact than JSON for tabular data, making it ideal for:

LLM prompts — fit more context in token limits
Data serialization — compact representation of structured data
API responses — human-readable but machine-parseable
Configuration files — cleaner syntax than JSON

Installation

Follow the n8n community nodes installation guide.

npm

npm install n8n-nodes-toon

n8n Cloud

In n8n Cloud or self-hosted n8n (v0.200+):

Go to Settings → Community Nodes
Select Install
Enter n8n-nodes-toon and agree to the risks
Click Install

The TOON node will appear in your node palette under the Transform category.

Operations

The TOON node supports two operations:

1. JSON to TOON

Convert JSON data to TOON format.

Input: JSON object or array
Output: TOON formatted text

Use case: Prepare data for LLM prompts, compact serialization

2. TOON to JSON

Parse TOON formatted text back to JSON.

Input: TOON formatted text
Output: JSON object or array

Use case: Parse LLM responses, deserialize TOON data

Configuration Options

Encoding Options (JSON→TOON)

Option	Type	Default	Description
Indent Size	Number	`2`	Spaces per indentation level
Delimiter	Choice	`comma`	Delimiter for array values (`comma`, `tab`, `pipe`)
Key Folding	Choice	`off`	Collapse single-key chains (`off`, `safe`)
Flatten Depth	Number	`999`	Maximum segments to fold (999 = unlimited)
Include Token Metrics	Boolean	`false`	Add token count comparison to output

Decoding Options (TOON→JSON)

Option	Type	Default	Description
Expected Indent Size	Number	`2`	Expected indentation for validation
Strict Mode	Boolean	`true`	Enforce array counts and indentation
Expand Paths	Choice	`off`	Split dotted keys (`off`, `safe`)

Input/Output Configuration

Option	Type	Default	Description
Input Data	String	`={{ $json }}`	Data to convert. Supports drag-and-drop, field names, dot notation, and expressions. Auto-detects input type.
Output Field	String	`data`	Field name for output

Input Data Details

The Input Data field auto-detects the input type:

Drag-and-drop: Drag fields from the left panel – automatically evaluated by n8n
Field names: Simple field access (e.g., data)
Dot notation: Nested access (e.g., users[0].name)
Expressions: Full n8n expressions (e.g., ={{ $json.users.filter(u => u.active) }})
Literal TOON (for decoding): If a string doesn't match a field path, treated as TOON data

Token Metrics Output

When Include Token Metrics is enabled for JSON→TOON conversion, the output includes a tokenMetrics object:

{
  "data": "users[2]{id,name}:\n  1,Alice\n  2,Bob",
  "tokenMetrics": {
    "json": 123,
    "toon": 58,
    "saved": 65,
    "reduction": 0.5285
  }
}

json: Estimated token count for JSON input
toon: Estimated token count for TOON output
saved: Number of tokens saved
reduction: Reduction ratio (0.5285 = 52.85% reduction)

Usage Examples

Example 1: LLM Context Preparation

Workflow: Fetch Users → JSON to TOON → Send to LLM

Use TOON to fit more context into LLM token limits while maintaining readability.

Input (JSON):

{
  "users": [
    {"id": 1, "name": "Alice", "role": "admin", "active": true},
    {"id": 2, "name": "Bob", "role": "user", "active": true},
    {"id": 3, "name": "Charlie", "role": "user", "active": false}
  ]
}

Output (TOON – comma delimiter):

users[3]{id,name,role,active}:
  1,Alice,admin,true
  2,Bob,user,true
  3,Charlie,user,false

Token Savings: ~40-50% fewer tokens than equivalent JSON for structured data.

Example 2: Parse LLM Structured Output

Workflow: Send Prompt to LLM → TOON to JSON → Process Data

LLMs can generate TOON format more reliably than JSON due to simpler syntax.

LLM Output (TOON):

result:
  tasks[3]{name,priority,status}:
    "Update docs",high,pending
    "Fix bug #123",high,done
    "Refactor code",low,pending
  summary: "3 tasks identified"

Parsed JSON:

{
  "result": {
    "tasks": [
      {"name": "Update docs", "priority": "high", "status": "pending"},
      {"name": "Fix bug #123", "priority": "high", "status": "done"},
      {"name": "Refactor code", "priority": "low", "status": "pending"}
    ],
    "summary": "3 tasks identified"
  }
}

Example 3: Working with CSV Data

n8n has excellent built-in CSV support via the "Extract from File" node. Use TOON for transformations:

Workflow: Read File → Extract from CSV → JSON to TOON → Transform → TOON to JSON → Use Data

Use n8n's "Extract from File" (CSV) node to parse CSV files
The extracted data is already JSON (one item per row)
Use "JSON to TOON" to convert to TOON format for LLM processing
Use "TOON to JSON" to convert back to JSON for further processing

Example 4: Key Folding for Nested Data

Workflow: API Request → JSON to TOON (Key Folding: Safe) → Transform

Simplify deeply nested JSON structures.

Input:

{
  "user": {
    "profile": {
      "name": "Alice",
      "email": "alice@example.com"
    }
  }
}

Output (with Key Folding):

user.profile.name: Alice
user.profile.email: alice@example.com

Example 5: Different Delimiters

Use tab delimiters for data with commas in values.

TOON (tab delimiter):

products[2]{id	name	price}:
  1	"Widget, Small"	9.99
  2	"Gadget, Large"	19.99

Use Cases

1. LLM Integration

Problem: JSON wastes tokens on quotes, brackets, and redundant keys.

Solution: TOON reduces token usage by 40-50% for structured data.

Workflow: Data Source → JSON to TOON → LLM → TOON to JSON → Process

2. API Response Transformation

Problem: API responses are verbose JSON that's hard to read in logs.

Solution: Convert to TOON for compact, human-readable logging.

Workflow: API Request → JSON to TOON → Log/Store → TOON to JSON → Use

3. Data Format Conversion

Problem: Need to transform data between different formats for different systems.

Solution: Use TOON as an intermediate format for transformations.

Workflow: Extract from CSV → JSON to TOON → Transform → TOON to JSON → Send to API

4. Configuration Management

Problem: JSON config files are verbose and don't support comments well.

Solution: Store configs in TOON format for better readability.

Workflow: Read TOON Config → TOON to JSON → Apply Settings

5. Report Generation

Problem: Need to generate readable reports from structured data.

Solution: Convert to TOON for human-friendly text representation.

Workflow: Fetch Data → JSON to TOON → Format Report → Send Email

Compatibility

n8n version: 0.200.0 or later
Node.js: 18.x or later
TOON Specification: v3.0

Specification Compliance

This node implements TOON Specification v3.0 with comprehensive coverage of all core features and major optional features.

Implemented Features

✅ Core Features (100%)

All JSON data types (objects, arrays, primitives)
Indentation-based structure with configurable spacing
Array length declarations [N]
Tabular arrays for uniform objects [N]{field1,field2}:
All three delimiters: comma (default), tab, pipe
Deterministic string quoting and escaping
Strict mode validation with array count and width checking

✅ Optional Features

Key Folding (keyFolding: "safe") – Collapse nested single-key objects into dotted paths (e.g., {a: {b: {c: 1}}} → a.b.c: 1)
Path Expansion (expandPaths: "safe") – Expand dotted keys back into nested objects during decoding

Not Implemented

❌ Hyphen Syntax for List-Item Objects (§10) – Optional YAML-style compact notation for objects in arrays. This is a purely cosmetic encoding optimization that doesn't affect functionality or data compatibility. Our implementation uses standard object indentation instead, which is equally spec-compliant and easier to maintain.

Round-Trip Guarantee

All JSON data can be encoded to TOON and decoded back to JSON with full fidelity. The implementation passes all conformance requirements for encoders and decoders per the specification.

Advanced Features

Strict Mode

When enabled (default), the decoder validates:

Array element counts match declared length
Indentation multiples match expected indent size
Proper structure and syntax

Disable for lenient parsing of hand-written TOON.

Path Expansion

Convert dotted keys into nested objects:

TOON:

user.name: Alice
user.email: alice@example.com

JSON (with expandPaths: safe):

{
  "user": {
    "name": "Alice",
    "email": "alice@example.com"
  }
}

Round-Trip Guarantees

TOON guarantees lossless round-trip conversion:

JSON → TOON → JSON preserves all data and structure
Works with any valid JSON input
Maintains data types (strings, numbers, booleans, null)

Zero Dependencies

This node has zero production dependencies:

Pure Node.js implementation
No external libraries required
Minimal package size
No security vulnerabilities from dependencies

Note: There is another package called n8n-nodes-toon (non-scoped) that wraps the official @toon-format/toon library. This package (@tehw0lf/n8n-nodes-toon) implements the TOON specification directly, resulting in zero production dependencies and full control over the implementation.

Troubleshooting

Issue: "Input must be a string" error

Cause: TOON to JSON operation expects string input.

Solution: Ensure input field contains TOON text, not a JSON object.

Issue: Strict mode validation errors

Cause: TOON data doesn't match expected structure.

Solution: Disable strict mode or fix indentation/counts in TOON data.

Issue: Key folding conflicts

Cause: Both user.name and user keys exist in same object.

Solution: Use keyFolding: "safe" which only folds when safe, or disable key folding.

Issue: Round-trip doesn't match exactly

Cause: TOON normalizes data (e.g., -0 → 0, sorts object keys).

Solution: This is expected — TOON preserves semantic meaning, not exact formatting.

Resources

TOON Specification v3.0: Official spec at github.com/toon-format/spec or see SPEC.md in this repository
n8n Documentation: https://docs.n8n.io/
Community Nodes Guide: https://docs.n8n.io/integrations/community-nodes/
GitHub Repository: https://github.com/tehw0lf/n8n-nodes-toon
Issues & Support: https://github.com/tehw0lf/n8n-nodes-toon/issues

License

MIT © tehw0lf

Author

tehw0lf tehwolf@protonmail.com

Contributing

Contributions are welcome! Please open an issue or pull request on GitHub.

Note: This node implements the TOON Specification v3.0. See SPEC.md for complete format documentation or visit the official spec repository.