RG.Toon 0.0.1

RG.Toon

A .NET implementation of the TOON (Token-Oriented Object Notation) serializer/deserializer.

TOON is a compact, human-readable encoding of the JSON data model, particularly efficient for arrays of uniform objects. It's designed to minimize LLM token consumptions while maintaining clear structure.

Installation

dotnet add package RG.Toon

Quick Start

using RG.Toon;

// Serialize an object to TOON
var items = new[]
{
    new { Id = 1, Name = "Alice", Active = true },
    new { Id = 2, Name = "Bob", Active = false }
};
string toon = ToonSerializer.Serialize(items);
// Output:
// [2]{Id,Name,Active}:
//   1,Alice,true
//   2,Bob,false

// Deserialize TOON back to objects
var result = ToonSerializer.Deserialize<Item[]>(toon);

Features

• Compact Format: TOON uses tabular format for arrays of uniform objects, reducing redundancy
• Human-Readable: Clean indentation-based syntax similar to YAML
• Full JSON Data Model Support: Objects, arrays, strings, numbers, booleans, and null
• Custom Property Naming: Use [ToonPropertyName] to customize serialized property names
• Property Ignoring: Use [ToonIgnore] to exclude properties from serialization

Format Examples

Simple Objects

var obj = new { Id = 123, Name = "Ada", Active = true };
var toon = ToonSerializer.Serialize(obj);

Output:

Id: 123
Name: Ada
Active: true

Nested Objects

var obj = new
{
    User = new
    {
        Name = "Ada",
        Address = new { City = "Boulder", Street = "Main St" }
    }
};
var toon = ToonSerializer.Serialize(obj);

Output:

User:
  Name: Ada
  Address:
    City: Boulder
    Street: Main St

Primitive Arrays

var obj = new { Tags = new[] { "admin", "ops", "dev" } };
var toon = ToonSerializer.Serialize(obj);

Output:

Tags[3]: admin,ops,dev

Tabular Arrays (Arrays of Uniform Objects)

var items = new[]
{
    new { Sku = "A1", Qty = 2, Price = 9.99m },
    new { Sku = "B2", Qty = 1, Price = 14.5m }
};
var obj = new { Items = items };
var toon = ToonSerializer.Serialize(obj);

Output:

Items[2]{Sku,Qty,Price}:
  A1,2,9.99
  B2,1,14.5

Attributes

ToonPropertyName

Use [ToonPropertyName] to customize the name of a property in the serialized output:

public record Person
{
    [ToonPropertyName("name")]
    public required string PersonName { get; init; }
    
    public int Age { get; init; }
}

var person = new Person { PersonName = "Ada", Age = 30 };
var toon = ToonSerializer.Serialize(person);
// Output:
// name: Ada
// Age: 30

ToonIgnore

Use [ToonIgnore] to exclude a property from serialization:

public record User
{
    public required string Name { get; init; }
    
    [ToonIgnore]
    public string NormalizedName => Name.ToUpperInvariant();
    
    public int Age { get; init; }
}

var user = new User { Name = "Ada", Age = 30 };
var toon = ToonSerializer.Serialize(user);
// Output:
// Name: Ada
// Age: 30
// (NormalizedName is not included)

API Reference

ToonSerializer.Serialize

// Serialize any object to TOON string
public static string Serialize<T>(T value, int indentSize = 2);
public static string Serialize(object? value, int indentSize = 2);

ToonSerializer.Deserialize

// Deserialize TOON string to strongly-typed object
public static T? Deserialize<T>(string toon, int indentSize = 2);
public static object? Deserialize(string toon, Type type, int indentSize = 2);

Quoting Rules

TOON follows specific quoting rules to maintain unambiguous parsing:

• Quoted Strings: Empty strings, strings that look like booleans (true, false), null, numbers, or contain special characters (:, ,, ", \, [, ], {, }, newlines)
• Unquoted Strings: Safe strings containing alphanumeric characters, underscores, dots, Unicode, and emoji

Escape Sequences

The following escape sequences are supported within quoted strings:

TOON Specification

This library implements TOON Specification v3.0.

For detailed format specification, encoding rules, and conformance requirements, refer to the official specification.

License

MIT License © Ronny Gunawan