Skip to main content
This page provides practical examples showing how TOON handles common data structures and real-world scenarios.

Basic Examples

Simple Configuration

appName: MyApp
version: 1.2.3
environment: production

server:
  host: localhost
  port: 8080
  ssl: true

features:
  auth: true
  analytics: false
  beta: false

User Profile

userId: 12345
username: alice_dev
email: [email protected]
verified: true
createdAt: 2024-01-15T10:30:00Z

profile:
  firstName: Alice
  lastName: Johnson
  bio: "Software engineer\nPython enthusiast"
  location: San Francisco, CA
  
settings:
  theme: dark
  notifications: true
  language: en-US

roles[3]: developer,admin,reviewer

Tabular Data Examples

Database Query Results

TOON excels at representing tabular data:
users[5]{id,username,email,lastLogin,active}:
  1,alice,[email protected],2024-03-15T10:30:00Z,true
  2,bob,[email protected],2024-03-14T15:45:00Z,true
  3,carol,[email protected],2024-03-10T08:20:00Z,false
  4,dave,[email protected],2024-03-16T09:15:00Z,true
  5,eve,[email protected],2024-03-13T14:30:00Z,true
Space comparison: TOON is ~45% smaller for this dataset.

Sales Data

quarterly_sales[4]{quarter,revenue,costs,profit,growth}:
  Q1-2024,1250000,850000,400000,12.5
  Q2-2024,1420000,920000,500000,15.3
  Q3-2024,1680000,980000,700000,18.2
  Q4-2024,1890000,1050000,840000,22.1

total_revenue: 6240000
total_profit: 2440000

Product Catalog

products[4]{sku,name,price,stock,category}:
  WDG-001,Widget Pro,29.99,150,widgets
  GDG-002,Gadget Plus,49.99,87,gadgets
  WDG-003,Widget Lite,19.99,203,widgets
  ACC-004,"Universal Adapter, 5V",12.99,324,accessories
Notice how the comma in “Universal Adapter, 5V” is automatically quoted to avoid delimiter confusion.

Nested Structures

API Response

status: success
timestamp: 2024-03-15T10:30:00Z

data:
  users[3]{id,name,role}:
    1,Alice,admin
    2,Bob,user
    3,Carol,moderator
  
  pagination:
    page: 1
    per_page: 10
    total: 3
    total_pages: 1

meta:
  request_id: req_abc123xyz
  duration_ms: 45

Organization Hierarchy

organization:
  name: TechCorp
  founded: 2015
  
  departments[3]:
    - name: Engineering
      headCount: 45
      teams[2]{name,size,lead}:
        Backend,12,Alice
        Frontend,8,Bob
    
    - name: Product
      headCount: 15
      teams[2]{name,size,lead}:
        Design,5,Carol
        Research,3,Dave
    
    - name: Sales
      headCount: 20
      regions[3]: NA,EMEA,APAC

Complex Real-World Examples

Test Suite Configuration

testSuite: API Integration Tests
version: 2.1.0
timeout: 30000
retries: 3

envs[3]{name,baseURL,apiKey}:
  dev,https://dev.api.example.com,dev_key_123
  staging,https://staging.api.example.com,stg_key_456
  prod,https://api.example.com,prod_key_789

tests[4]:
  - name: User Authentication
    endpoint: /auth/login
    method: POST
    expectedStatus: 200
    assertions[3]:
      - field: token
        type: string
      - field: expiresIn
        type: number
      - field: user.id
        type: number
  
  - name: Create User
    endpoint: /users
    method: POST
    expectedStatus: 201
    headers[2]{key,value}:
      Content-Type,application/json
      Authorization,Bearer {{token}}
    body:
      username: testuser
      email: [email protected]
  
  - name: Get User List
    endpoint: /users
    method: GET
    expectedStatus: 200
    params[2]{key,value}:
      page,1
      limit,10
  
  - name: Delete User
    endpoint: /users/{{userId}}
    method: DELETE
    expectedStatus: 204

Machine Learning Dataset

dataset: Customer Churn Prediction
version: 1.0.0
samples: 5000

features[8]{name,type,min,max,mean,stddev}:
  age,numeric,18,95,42.5,15.2
  tenure_months,numeric,1,120,34.8,22.1
  monthly_charges,numeric,18.25,118.75,64.76,30.09
  total_charges,numeric,18.80,8684.80,2283.30,2266.77
  contract_type,categorical,0,2,1.0,0.82
  payment_method,categorical,0,3,1.5,1.12
  internet_service,categorical,0,2,1.2,0.75
  num_services,numeric,0,6,2.8,1.5

target:
  name: churn
  type: binary
  distribution[2]{label,count,percentage}:
    0,3652,73.04
    1,1348,26.96

splits[3]{name,samples,percentage}:
  train,3500,70.0
  validation,750,15.0
  test,750,15.0

Delimiter Variants

Tab-Separated Values

Use --tab flag for tab-separated data:
# Array header shows space marker: [3 ]
data[3 ]{name    age    city}:
  Alice    30    NYC
  Bob    25    LA
  Carol    35    SF
Tab delimiters are ideal for data with many commas or when importing from TSV files.

Pipe-Separated Values

Use --pipe flag for pipe-separated data:
# Array header shows pipe marker: [3|]
data[3|]{name,age,city}:
  Alice|30|NYC
  Bob|25|LA
  Carol|35|SF
Pipe delimiters work well when your data contains both commas and tabs.

Edge Cases

Special Characters in Data

data[4]{field,value}:
  "with,comma","Contains, commas"
  "with:colon","Key: value format"
  "with\"quote","She said \"hello\""
  "with\nline","Line 1\nLine 2"

Empty and Null Values

data[5]{id,name,email,phone}:
  1,Alice,[email protected],555-0100
  2,Bob,null,555-0101
  3,Carol,[email protected],null
  4,"","",""
  5,Eve,[email protected],555-0103

Mixed Primitives

mixed[8]: 42,hello,true,null,3.14,false,"quoted string",0

Optional Features

Length Markers

Use --length-marker for explicit array size indicators:
data[100]{id,value}:
  ...

Key Folding

Use --key-folding to flatten nested single-key objects:
user:
  profile:
    settings:
      theme: dark
Both represent the same nested structure in JSON.

Performance Comparison

Space savings on a real-world 1000-record dataset:
FormatSizeSavings
JSON145 KBbaseline
JSON (minified)89 KB39%
TOON (tabular)52 KB64%
TOON (compressed)12 KB92%
TOON’s tabular format provides significant space savings while maintaining readability, making it ideal for version control and human review.

Next Steps

CLI Usage

Learn how to convert files with the CLI tool

CLI Options

Explore all available conversion options

Python API

Use TOON in your Python applications

TOON Overview

Return to the format overview

Build docs developers (and LLMs) love