Skip to main content
The TOON JSON Converter provides two configuration classes to control encoding and decoding behavior.

​
EncodeOptions

Controls how Python objects are encoded to TOON format. 
from toon_json_converter import EncodeOptions, Delimiter

options = EncodeOptions(
    indent_size=2,
    delimiter=Delimiter.COMMA,
    length_marker=False,
    key_folding=False,
    flatten_depth=float('inf')
)

​
Fields

​
indent_size
int
default:"2"
Number of spaces per indentation level. Common values are 2 or 4.
# 2-space indentation (default)
options = EncodeOptions(indent_size=2)
# Output:
# user:
#   name: Alice

# 4-space indentation
options = EncodeOptions(indent_size=4)
# Output:
# user:
#     name: Alice
​
delimiter
Delimiter
default:"Delimiter.COMMA"
Delimiter used for separating values in primitive and tabular arrays.Available values:
  • Delimiter.COMMA - Comma delimiter (,)
  • Delimiter.TAB - Tab delimiter (\t)
  • Delimiter.PIPE - Pipe delimiter (|)
from toon_json_converter import Delimiter

# Comma (default)
options = EncodeOptions(delimiter=Delimiter.COMMA)
# Output: values[3]: 1,2,3

# Tab
options = EncodeOptions(delimiter=Delimiter.TAB)
# Output: values[3 ]: 1\t2\t3

# Pipe
options = EncodeOptions(delimiter=Delimiter.PIPE)
# Output: values[3|]: 1|2|3
​
length_marker
bool
default:"False"
Whether to add a # prefix to array lengths in headers.
# Without length marker (default)
options = EncodeOptions(length_marker=False)
# Output: items[5]: 1,2,3,4,5

# With length marker
options = EncodeOptions(length_marker=True)
# Output: items[#5]: 1,2,3,4,5
​
key_folding
bool
default:"False"
Whether to collapse nested single-key objects using dot notation.
data = {
    "database": {
        "connection": {
            "host": "localhost"
        }
    }
}

# Without key folding (default)
options = EncodeOptions(key_folding=False)
# Output:
# database:
#   connection:
#     host: localhost

# With key folding
options = EncodeOptions(key_folding=True)
# Output:
# database.connection.host: localhost
​
flatten_depth
int
default:"float('inf')"
Maximum depth for key folding. Controls how many levels deep the key folding will go. Only relevant when key_folding=True.
data = {
    "a": {
        "b": {
            "c": {
                "d": "value"
            }
        }
    }
}

# Unlimited depth (default)
options = EncodeOptions(
    key_folding=True,
    flatten_depth=float('inf')
)
# Output: a.b.c.d: value

# Limited to 2 levels
options = EncodeOptions(
    key_folding=True,
    flatten_depth=2
)
# Output:
# a.b:
#   c:
#     d: value

​
Complete Example

from toon_json_converter import TOONEncoder, EncodeOptions, Delimiter

# Create custom encoding options
options = EncodeOptions(
    indent_size=4,
    delimiter=Delimiter.TAB,
    length_marker=True,
    key_folding=True,
    flatten_depth=2
)

encoder = TOONEncoder(options)

data = {
    "config": {
        "database": {
            "host": "localhost"
        }
    },
    "users": [
        {"name": "Alice", "age": 30},
        {"name": "Bob", "age": 25}
    ]
}

toon = encoder.encode(data)
print(toon)
Output: 
config.database.host: localhost
users[#2 ]{name,age}:
    Alice    30
    Bob      25

​
DecodeOptions

Controls how TOON format is decoded to JSON/Python objects. 
from toon_json_converter import DecodeOptions

options = DecodeOptions(
    pretty=True,
    indent=2,
    expand_paths=False
)

​
Fields

​
pretty
bool
default:"True"
Whether to format JSON output with indentation and newlines. When False, produces minified (compact) JSON.
# Pretty formatted JSON (default)
options = DecodeOptions(pretty=True)
# Output:
# {
#   "name": "Alice",
#   "age": 30
# }

# Compact JSON
options = DecodeOptions(pretty=False)
# Output:
# {"name":"Alice","age":30}
​
indent
int
default:"2"
Number of spaces per indentation level in JSON output. Only used when pretty=True.
# 2-space indentation (default)
options = DecodeOptions(pretty=True, indent=2)
# Output:
# {
#   "user": {
#     "name": "Alice"
#   }
# }

# 4-space indentation
options = DecodeOptions(pretty=True, indent=4)
# Output:
# {
#     "user": {
#         "name": "Alice"
#     }
# }
​
expand_paths
bool
default:"False"
Whether to expand dotted keys (e.g., database.connection.host) into nested objects.Per TOON specification §13.4, this option is OFF by default to preserve dotted keys as literal key names.
# TOON input:
# database.connection.host: localhost

# Without path expansion (default)
options = DecodeOptions(expand_paths=False)
# Output:
# {
#   "database.connection.host": "localhost"
# }

# With path expansion
options = DecodeOptions(expand_paths=True)
# Output:
# {
#   "database": {
#     "connection": {
#       "host": "localhost"
#     }
#   }
# }

​
Complete Example

from toon_json_converter import BidirectionalConverter, DecodeOptions

# Create custom decoding options
options = DecodeOptions(
    pretty=True,
    indent=4,
    expand_paths=True
)

converter = BidirectionalConverter(decode_options=options)

# Convert TOON to JSON with custom formatting
converter.convert_file('data.toon', 'data.json')
With TOON input: 
app.name: MyApp
app.version: 1.0.0
server.host: localhost
server.port: 8080
JSON output (with expand_paths=True): 
{
    "app": {
        "name": "MyApp",
        "version": "1.0.0"
    },
    "server": {
        "host": "localhost",
        "port": 8080
    }
}

​
Using Options Together

You can use both encoding and decoding options with the BidirectionalConverter: 
from toon_json_converter import (
    BidirectionalConverter,
    EncodeOptions,
    DecodeOptions,
    Delimiter
)

converter = BidirectionalConverter(
    encode_options=EncodeOptions(
        indent_size=4,
        delimiter=Delimiter.TAB,
        length_marker=True,
        key_folding=True
    ),
    decode_options=DecodeOptions(
        pretty=True,
        indent=4,
        expand_paths=True
    )
)

# JSON → TOON uses encode_options
converter.convert_file('data.json', 'data.toon')

# TOON → JSON uses decode_options
converter.convert_file('data.toon', 'data.json')

​
Default Values Summary

​
EncodeOptions Defaults

FieldDefaultType
indent_size2int
delimiterDelimiter.COMMADelimiter
length_markerFalsebool
key_foldingFalsebool
flatten_depthfloat('inf')int

​
DecodeOptions Defaults

FieldDefaultType
prettyTruebool
indent2int
expand_pathsFalsebool

Build docs developers (and LLMs) love

Get started for freeTalk to us