AyCode.Core/AyCode.Core/docs/TOON/README.md

TOON — Token-Oriented Object Notation

LLM-optimized serializer. Primary goal: maximize LLM accuracy via schema/data separation, rich metadata, unambiguous boundaries. Serialize-only (no deserializer — see TOON_TODO.md#accore-toon-t-f3x1).

Source: Serializers/Toons/ in this project.

Design goals

1. Zero ambiguity — explicit {} / [] / """ boundaries; no indentation-only scoping.
2. Rich semantic context — every property carries description, purpose, constraints, examples in schema.
3. Token efficiency — schema once (@meta/@types), data streamed (@data); enum values numeric.
4. Smart defaults — useful output without attributes; ToonDescriptionAttribute for precision where conventions fall short.

Three-section output

Section	Contents
@meta	Format version, source language, type list, optional domain context.
@types	Per-type schema — description, purpose, constraints, examples, navigation metadata, enum value maps.
@data	Object instance values; nested with inline references for shared/circular objects.

Three modes (ToonSerializationMode)

Mode	When to use
Full (default)	First serialization — LLM needs full schema + data.
MetaOnly	Send schema once at conversation start.
DataOnly	Subsequent sends; LLM has the schema already — 30-50% token savings.

Details, preset breakdown, all options: TOON_OPTIONS.md.

Quick start

using AyCode.Core.Serializers.Toons;

var person = new Person { Id = 1, Name = "Alice", Email = "alice@example.com" };
string toon = AcToonSerializer.Serialize(person);

Output (Full mode, abbreviated — full grammar in TOON_FORMAT.md):

@meta { version = "1.0", format = "toon", types = ["Person"] }
@types {
  Person:
    Id: int32     (description, purpose, constraints: "required")
    Name: string  (description, constraints: "required")
    Email: string (description, constraints: "required, email-format")
}
@data {
  Person { Id = 1, Name = "Alice", Email = "alice@example.com" }
}

Multi-turn pattern

// Turn 1 — send schema only
string schema = AcToonSerializer.Serialize(person, AcToonSerializerOptions.MetaOnly);

// Turn 2..N — send data only (LLM already has the schema from Turn 1)
string data = AcToonSerializer.Serialize(person, AcToonSerializerOptions.DataOnly);

Public API entry points

Method	Purpose
AcToonSerializer.Serialize<T>(T value)	Default options (Full mode).
AcToonSerializer.Serialize<T>(T value, AcToonSerializerOptions)	Custom options.
AcToonSerializer.Serialize<T>(T value, string domainDescription, AcToonSerializerOptions)	Adds context = "..." to @meta.
AcToonSerializer.SerializeTypeMetadata<T>() / SerializeTypeMetadata(Type)	Schema only (MetaOnly preset internally).
AcToonSerializer.SerializeMetadata(IEnumerable<Type>) / SerializeMetadata(params Type[])	Schema for multiple types without an instance.

Choosing between Toon, AcBinary, AcJson

Use case	Choose
Wire format for LLM context / prompts	Toon
High-throughput wire format for non-LLM transport	AcBinary — see ../BINARY/README.md
Interop with external JSON consumers	AcJson

Full serializer comparison: see ../../Serializers/README.md.

Files in this folder

• README.md — this file (overview + navigation).
• TOON_FORMAT.md — wire format specification (exact grammar).
• TOON_OPTIONS.md — AcToonSerializerOptions reference, presets, API overloads.
• TOON_INFERENCE.md — smart description/constraint auto-generation from property names.
• TOON_ATTRIBUTES.md — ToonDescriptionAttribute API + placeholder system.
• TOON_IMPLEMENTATION.md — internals, partial class breakdown, context pattern.
• TOON_ISSUES.md — known limitations.
• TOON_TODO.md — planned work.

Cross-references

• Shared serializer infrastructure (metadata cache, reference tracking, IdentityMap): ../../Serializers/README.md.
• Folder-README-first navigation rule: ../../../.github/copilot-instructions.md rule #21.