Description

@tehw0lf/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.

Table of Contents

• 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 @tehw0lf/n8n-nodes-toon

n8n Cloud

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

1. Go to Settings → Community Nodes
2. Select Install
3. Enter @tehw0lf/n8n-nodes-toon and agree to the risks
4. 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,Alicen  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

1. Use n8n’s “Extract from File” (CSV) node to parse CSV files
2. The extracted data is already JSON (one item per row)
3. Use “JSON to TOON” to convert to TOON format for LLM processing
4. 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.

Automated Monitoring

This repository includes automated workflows for continuous monitoring:

Specification Monitoring

Monitors the official TOON specification for updates:

• Frequency: Checks run every Monday at 9:00 AM UTC
• Automatic Detection: Compares toonSpecVersion in package.json against the upstream GitHub Releases API
• Issue Creation: Automatically opens a GitHub issue when updates are detected
• Manual Trigger: Can be triggered manually via GitHub Actions

When a specification update is detected, the workflow:
1. Creates a labeled issue (spec-update, enhancement) with version details
2. Includes a diff summary showing the changes
3. Provides links to the official specification
4. Avoids duplicate issues for the same version

See .github/workflows/monitor-spec.yml for implementation details.

Security Monitoring

Performs comprehensive security scanning to detect vulnerabilities:

• Frequency: Runs daily at 2:00 AM UTC
• Source Code Scanning: Semgrep analysis for security issues (OWASP Top 10, etc.)
• Dependency Scanning: npm audit on dependencies
• Published Package Scanning: Checks the live npm package for newly disclosed vulnerabilities
• Automatic Trigger: Also runs on changes to package.json or package-lock.json

When vulnerabilities are detected, the workflow:
1. Creates a labeled issue (security, vulnerability, dependencies)
2. Includes severity levels and full audit report
3. Provides remediation guidance with specific commands
4. Updates existing issues instead of creating duplicates

See .github/workflows/security-scan.yml for implementation details.

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

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.