Skip to main content

​
Overview

The TOON JSON Converter provides a simple command-line interface that automatically detects the conversion direction based on file extensions.

​
Basic Syntax

python toon_json_converter.py <input> [output] [options]
​
input
string
required
Input file or folder path. The file extension determines the conversion direction:
  • .json - Converts to TOON format
  • .jsonl - Converts to folder of TOON files
  • .toon - Converts to JSON format
  • folder/ - Converts all TOON files to JSONL
​
output
string
Output file or folder path. If omitted, automatically generates output path based on input:
  • data.json → data.toon
  • data.jsonl → data_toons/
  • data.toon → data.json
  • data_folder/ → data_folder.jsonl

​
Conversion Modes

The converter supports four bidirectional conversion modes:

​
1. JSON to TOON

python toon_json_converter.py input.json output.toon
Converts a single JSON file to TOON format.

​
2. JSONL to TOON Folder

python toon_json_converter.py input.jsonl output_folder/
Converts each line in a JSONL file to a separate TOON file in a folder.

​
3. TOON to JSON

python toon_json_converter.py input.toon output.json
Converts a single TOON file to JSON format.

​
4. TOON Folder to JSONL

python toon_json_converter.py input_folder/ output.jsonl
Converts all TOON files in a folder to a single JSONL file.

​
Command-Line Options

​
General Options

​
-o, --output
string
Specify output file or folder path. Alternative to using positional argument.
python toon_json_converter.py data.json -o output.toon
python toon_json_converter.py data.toon --output result.json

​
Encoding Options (JSON → TOON)

These options apply when converting FROM JSON or JSONL TO TOON:
​
--tab
flag
Use tab (\t) as the delimiter for tabular arrays instead of comma.Default: Comma (,)Line reference: toon_json_converter.py:1215-1216
python toon_json_converter.py data.json data.toon --tab
Example output:
users[3 ]{name,age}:
  Alice\t30
  Bob\t25
  Carol\t35
​
--pipe
flag
Use pipe (|) as the delimiter for tabular arrays instead of comma.Default: Comma (,)Line reference: toon_json_converter.py:1217-1218
python toon_json_converter.py data.json data.toon --pipe
Example output:
users[3|]{name,age}:
  Alice|30
  Bob|25
  Carol|35
​
--length-marker
flag
Add # prefix to array lengths in headers for improved readability.Default: No prefixLine reference: toon_json_converter.py:1219-1220
python toon_json_converter.py data.json data.toon --length-marker
Example output:
items[#5]: apple, banana, cherry, date, fig
​
--key-folding
flag
Enable key folding for nested single-key objects. Converts chains like {"a": {"b": {"c": value}}} to a.b.c: value.Default: DisabledLine reference: toon_json_converter.py:1221-1222Requirements: Keys must match pattern [A-Za-z_][A-Za-z0-9_]*
python toon_json_converter.py data.json data.toon --key-folding
Example transformation:
{"server": {"config": {"port": 8080}}}
Becomes:
server.config.port: 8080

​
Decoding Options (TOON → JSON)

These options apply when converting FROM TOON TO JSON or JSONL:
​
--compact
flag
Output minified JSON without whitespace or indentation.Default: Pretty-printed with 2-space indentationLine reference: toon_json_converter.py:1228-1229
python toon_json_converter.py data.toon data.json --compact
Example output:
{"name":"Alice","age":30,"active":true}
​
--indent
integer
Set the number of spaces for JSON indentation.Default: 2Line reference: toon_json_converter.py:1232-1238
python toon_json_converter.py data.toon data.json --indent 4
Example output:
{
    "name": "Alice",
    "age": 30
}
​
--expand-paths
flag
Expand dotted keys into nested objects during TOON → JSON conversion.Default: Disabled (per TOON spec §13.4)Line reference: toon_json_converter.py:1230-1231
python toon_json_converter.py data.toon data.json --expand-paths
Example transformation:TOON input:
server.config.port: 8080
server.config.host: localhost
Without --expand-paths (default):
{
  "server.config.port": 8080,
  "server.config.host": "localhost"
}
With --expand-paths:
{
  "server": {
    "config": {
      "port": 8080,
      "host": "localhost"
    }
  }
}

​
Exit Codes

The converter returns the following exit codes:
CodeMeaning
0Success
1Error (missing arguments, file not found, conversion error)

​
Examples

​
Convert with Custom Delimiter

python toon_json_converter.py data.json data.toon --tab --length-marker

​
Convert with Multiple Options

python toon_json_converter.py data.json output.toon --pipe --key-folding --length-marker

​
Convert to Compact JSON

python toon_json_converter.py data.toon data.json --compact

​
Batch Convert with Custom Output

python toon_json_converter.py dataset.jsonl -o toon_files/ --tab

​
Help Command

Run the converter without arguments to display usage information: 
python toon_json_converter.py
Output: 
Bidirectional TOON ↔ JSON/JSONL Converter

Usage: python toon_json_converter.py <input> [output] [options]

Automatic direction detection:
  .json file      → .toon file
  .jsonl file     → folder of .toon files
  .toon file      → .json file
  folder of .toon → .jsonl file

Options:
  -o, --output <path>   Output file/folder path

  Encoding options (JSON → TOON):
    --tab               Use tab delimiter
    --pipe              Use pipe delimiter
    --length-marker     Add # prefix to array lengths
    --key-folding       Enable key folding for nested objects

  Decoding options (TOON → JSON):
    --compact           Minified JSON output
    --indent <n>        Set indentation spaces (default: 2)
    --expand-paths      Expand dotted keys into nested objects (§13.4, off by default)

​
Next Steps

Conversion Modes

Learn about all four conversion modes in detail

Options Guide

Deep dive into all command-line options

Batch Conversion

Process multiple files efficiently

Quick Start

Get started with basic examples

Build docs developers (and LLMs) love

Get started for freeTalk to us