Format Overview

TONL syntax reference with concrete examples. See Documentation for full API reference.

Data Model

TONL models data the same way as JSON:

• Primitives: strings, numbers, booleans, and null
• Objects: mappings from string keys to values
• Arrays: ordered sequences of values

Root Forms

A TONL document can represent different root forms:

• Root object (most common): Fields appear at depth 0 with no parent key
• Root array: Begins with key[N]{fields}: at depth 0
• Root primitive: A single primitive value (string, number, boolean, or null)

Document Headers

TONL documents can include optional metadata headers at the top.

Version Header

#version 1.0

Specifies the TONL format version. Defaults to 1.0 if omitted.

Delimiter Header

#delimiter "|"

Declares the column separator for tabular data. Supported delimiters:

Complete Header Example

#version 1.0
#delimiter "|"

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

Objects

Objects use indentation-based syntax. One space follows the colon.

Simple Objects

Objects with primitive values use key: value syntax:

id: 123
name: Ada
active: true

Objects with Type Hints

Type hints are optional and appear in the header:

user{id:u32,name:str,active:bool}:
  id: 123
  name: Ada
  active: true

The header user{id:u32,name:str,active:bool}: declares object name and field types.

Nested Objects

Nested objects add one indentation level (default: 2 spaces):

user{id:u32,name:str,contact:obj}:
  id: 1
  name: Alice
  contact{email:str,phone:str}:
    email: alice@example.com
    phone: +123456789

Empty Objects

A nested empty object is key: alone, with no children:

user{id:u32,metadata:obj}:
  id: 1
  metadata:

Arrays

TONL detects array structure and chooses the most efficient representation. Arrays declare their length in brackets: [N].

Primitive Arrays (Inline)

Arrays of primitives are rendered inline:

tags[3]: admin, ops, dev
scores[4]: 95, 87, 92, 100
flags[3]: true, false, true

Arrays of Objects (Tabular)

When all objects share the same primitive-valued keys, TONL uses tabular format:

users[3]{id:u32,name:str,role:str}:
  1, Alice, admin
  2, Bob, user
  3, Carol, editor

With Quoted Values

Strings containing the delimiter must be quoted:

users[2]{id:u32,name:str,role:str}:
  1, Alice Admin, admin
  2, "Bob, Jr.", user

Empty Arrays

items[0]:

The header declares length zero, with no elements following.

Type Hints

Type hints are optional annotations that provide schema information in the header.

Syntax

key{field:type,field:type,...}:

Available Types

Type Inference

When type hints are omitted, the decoder infers types automatically:

Type Coercion

In strict mode, values are coerced to match type hints:

user{age:u32,name:str,active:bool}:
  age: "25"           # Coerced to number 25
  name: alice         # Coerced to string "alice"
  active: "true"      # Coerced to boolean true

Quoting and Types

TONL quotes strings only when necessary to maximize token efficiency.

When Strings Need Quotes

A string must be quoted if:

• It's empty ("")
• It has leading or trailing whitespace
• It equals true, false, or null
• It looks like a number (e.g., "42", "-3.14")
• It contains special characters: : , # {} [] " \
• It contains the active delimiter character

Otherwise, strings can be unquoted. Unicode, emoji, and internal spaces are safe:

message: Hello world
note: This has inner spaces
emoji: Check this out

Escape Sequences

Multiline Strings

Triple quotes (""") are used for multiline content:

description: """This is a
multi-line string
with preserved formatting"""

Type Conversions

Key Handling

Rules for object keys and special character handling.

Valid Identifiers

• Characters: Letters, numbers, underscore (_)
• First character: Must be a letter or underscore
• Case sensitivity: Case-sensitive

valid_name: value
isValid123: value
_privateField: value

Quoted Keys (Special Characters)

Keys containing special characters must be quoted:

"field-with-dash": value
"key with spaces": value
"@type": value
"#comment": value

Dual-Mode System (v2.0.6+)

TONL offers two modes for handling problematic keys:

""[1]:
  empty-value
"#"[1]:
  hash-value

empty[1]:
  empty-value
comment[1]:
  hash-value

Complete Examples

Real-world TONL document examples.

E-commerce Order

@tonl v1

order{orderId,status,placedAt}:
  orderId: ORD-2025-11-001234
  status: processing
  placedAt: 2025-11-03T14:30:00Z

customer{id:u32,name:str,email:str,tier:str}:
  id: 5678
  name: "John Smith"
  email: john.smith@example.com
  tier: premium

items[3]{sku,name,quantity:u32,unitPrice:f64,discount:f64}:
  WIDGET-001, "Premium Widget", 2, 29.99, 0.10
  GADGET-042, "Smart Gadget Pro", 1, 149.99, 0.00
  ACCESSORY-123, "Universal Adapter", 3, 12.99, 0.15

summary{subtotal:f64,tax:f64,shipping:f64,total:f64}:
  subtotal: 248.93
  tax: 21.16
  shipping: 9.99
  total: 266.63

notes[2]: "Gift wrap requested", "Leave package at front door"

User Profile with Nested Data

#version 1.0

user{id:u32,name:str,email:str,preferences:obj}:
  id: 1
  name: Ahmet Yilmaz
  email: ahmet@example.com
  preferences{language:str,notifications:bool,theme:str}:
    language: tr
    notifications: true
    theme: dark

stats{loginCount:u32,sessionDuration:f64}:
  loginCount: 156
  sessionDuration: 45.2

roles[3]: admin, editor, viewer

JSON Comparison

See how TONL compares to JSON in terms of size and token efficiency.