Skip to main content
Get started with TOON JSON Converter by following these quick examples. The converter automatically detects the conversion direction based on file extensions.

​
Your First Conversion

1

Prepare sample JSON data

Create a file called example.json with some sample data:
example.json
{
  "name": "Alice",
  "age": 30,
  "active": true,
  "scores": [95, 87, 92],
  "address": {
    "city": "Portland",
    "state": "OR"
  }
}
2

Convert JSON to TOON

Run the converter:
python toon_json_converter.py example.json
This creates example.toon with the following content:
example.toon
name: Alice
age: 30
active: true
scores[3]: 95,87,92
address:
  city: Portland
  state: OR
Notice how the array [95, 87, 92] is represented as scores[3]: 95,87,92 - the [3] indicates the array length.
3

Convert back to JSON

Now convert the TOON file back to JSON:
python toon_json_converter.py example.toon output.json
The output.json file will contain the original JSON structure, pretty-printed by default.

​
Tabular Data Example

TOON format excels at representing tabular data. Here’s how arrays of objects are handled: 
{
  "users": [
    {"id": 1, "name": "Alice", "role": "admin"},
    {"id": 2, "name": "Bob", "role": "user"},
    {"id": 3, "name": "Carol", "role": "user"}
  ]
}
Convert it: 
python toon_json_converter.py input.json output.toon
The header users[3]{id,name,role}: tells the parser:
  • [3] - array has 3 items
  • {id,name,role} - each object has these fields in this order
  • Data rows follow with comma-separated values

​
Batch Conversion

​
JSONL to Multiple TOON Files

Convert a JSONL (JSON Lines) file where each line is a separate JSON object: 
python toon_json_converter.py data.jsonl toon_output/
This creates a folder toon_output/ with files like:
  • data_0000.toon
  • data_0001.toon
  • data_0002.toon

​
Folder of TOON Files to JSONL

Convert multiple TOON files back to a single JSONL file: 
python toon_json_converter.py toon_output/ combined.jsonl

​
Conversion Options

Customize your conversions with command-line options:

​
Encoding Options (JSON → TOON)

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

​
Decoding Options (TOON → JSON)

python toon_json_converter.py data.toon data.json --compact
# No indentation, single-line output

​
Using in Python Code

You can also use the converter programmatically: 
from toon_json_converter import (
    BidirectionalConverter,
    EncodeOptions,
    DecodeOptions,
    Delimiter
)

# Configure encoding options
encode_opts = EncodeOptions(
    indent_size=2,
    delimiter=Delimiter.COMMA,
    length_marker=False,
    key_folding=True
)

# Configure decoding options
decode_opts = DecodeOptions(
    pretty=True,
    indent=2,
    expand_paths=False
)

# Create converter
converter = BidirectionalConverter(encode_opts, decode_opts)

# Convert files automatically
converter.convert_file("input.json", "output.toon")
converter.convert_file("input.toon", "output.json")

​
Direct Encoding/Decoding

For working with data in memory: 
from toon_json_converter import TOONEncoder, TOONParser
import json

# Encode Python data to TOON string
encoder = TOONEncoder()
data = {"name": "Alice", "scores": [95, 87, 92]}
toon_string = encoder.encode(data)
print(toon_string)
# Output:
# name: Alice
# scores[3]: 95,87,92

# Parse TOON string to Python data
parser = TOONParser()
toon_content = """name: Alice
scores[3]: 95,87,92"""
result = parser.parse(toon_content)
print(json.dumps(result, indent=2))
# Output:
# {
#   "name": "Alice",
#   "scores": [95, 87, 92]
# }

​
Common Patterns

​
Primitive Arrays

Arrays of simple values (strings, numbers, booleans) are written inline: 
tags[4]: python,converter,json,toon
numbers[5]: 1,2,3,4,5
flags[3]: true,false,true

​
Nested Objects

Objects can be nested naturally: 
config:
  database:
    host: localhost
    port: 5432
  cache:
    enabled: true
    ttl: 3600

​
List of Objects

Arrays containing non-uniform objects or nested structures: 
items[2]:
  - name: Item 1
    tags[2]: new,featured
  - name: Item 2
    tags[1]: sale

​
Next Steps

CLI Options

Explore all encoding and decoding options

TOON Format

Learn the TOON format specification

API Reference

Browse the complete API documentation

Examples

See more real-world examples

Build docs developers (and LLMs) love

Get started for freeTalk to us