# 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

```csharp
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`):

```toon
@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

```csharp
// 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.