TON File Format Specification

Introduction

TON (Text Object Notation) is a modern, performance-optimized file format designed for data serialization and configuration management. Unlike JSON where nodes are explicitly typed as objects, arrays, or primitives, TON treats all nodes as objects with properties, while also supporting explicit arrays using square bracket notation.

Key Features

• Object-Centric Design: All nodes are objects with properties and optional child objects
• Flexible Property Naming: Support for numeric property names, optional @ prefixes, and quoted names for special characters
• Multi-line String Literals: Triple-quoted strings with intelligent indentation handling
• Rich Data Types: Numbers (decimal, hex, binary), booleans, null, undefined, GUIDs, enums, dates, and arrays
• Performance Optimized: Reserved character optimization and property ordering for fast parsing
• Schema Validation: Comprehensive type system with class definitions, constraints, and default values
• Path-Based Validation: Apply validation rules to deeply nested properties using path-like specifiers
• UTF-8 Native: Full Unicode support with UTF-8 encoding requirement
• Comments: Single-line (//, #) and multi-line (/* */) comments for documentation

Quick Example

{(user)
    id = 12345,
    name = "John Doe",
    email = "[email protected]",
    isActive = true,
    joinDate = "2024-01-15T09:30:00Z",

    details = {
        bio = """
        Experienced software engineer with a passion for
        clean code and innovative solutions.
        """,
        avatar = "avatar.jpg"
    },

    skills = ["JavaScript", "TypeScript", "Python", "Go"],
    role = |senior_developer|,
    permissions = |read|write|review|deploy|
}

#! {(user)
    /id = int(required, positive),
    /name = string(required, maxLength(100)),
    /email = string(required, format(email)),
    /details/bio = string(maxLength(1000)),
    /skills = array:string(minCount(1), maxCount(20))
}

Why TON?

Comparison with JSON

Key Advantages

Over JSON

• Multi-line strings with intelligent indentation
• Numeric property names without quotes
• Rich type system (hex/binary numbers, GUIDs, enums)
• Comments support
• Schema validation built-in
• null vs undefined distinction

Over YAML

• Faster parsing with reserved character optimization
• Deterministic structure with property ordering
• Type safety with comprehensive schema system
• No indentation-based structure confusion

Over XML

• Human readable without tag verbosity
• Compact representation
• Built-in data types without string conversion
• Schema validation without external DTD/XSD

Use Cases

• Configuration Files: Application settings with validation and type safety
• API Documentation: Structured documentation with code examples
• Data Exchange: Between services with schema validation
• Database Schemas: Table definitions and migrations
• Test Data: Complex test fixtures with clear structure

Getting Started

To start using TON in your projects:

1. Learn the Syntax: Review the Syntax & Grammar documentation
2. Understand Data Types: Explore the Data Types reference
3. Define Schemas: Learn about Schema Definition and validation
4. See Examples: Check out practical Examples & Use Cases

Implementations

Official implementations are available for:

• C#/.NET: TONfile - Complete parser, validator, and serializer
• JavaScript/TypeScript: Coming soon
• Python: Coming soon
• Go: Coming soon

File Extensions and MIME Types

• Primary Extension: .ton
• Alternative Extension: .tondata
• MIME Type: application/ton

Specification Status

Contributing

We welcome contributions to the TON specification and implementations. Please see our Contributing Guide for details.

License

The TON specification is released under the MIT License. See License for details.