AyCode.Core/AyCode.Core/docs/TOON/TOON_OPTIONS.md

Toon — Options & Presets

AcToonSerializerOptions controls every Toon output behavior. Definition: Serializers/Toons/AcToonSerializerOptions.cs.

Toon-specific options

Option	Type	Default	Purpose
Mode	ToonSerializationMode	Full	Which sections to emit.
UseMeta	bool	true	Include @meta/@types sections. Ignored when Mode = DataOnly.
UseIndentation	bool	true	Pretty-print with indentation. When false, = has no surrounding spaces.
IndentString	string	" " (2 spaces)	Indent unit when UseIndentation = true.
UseInlineTypeHints	bool	false	Emit value <type> hints in @data (schema already has type info).
UseInlineComments	bool	false	Emit property descriptions as inline comments.
ShowCollectionCount	bool	true	Emit <Type[]> (count: N) header on arrays/dictionaries.
UseMultiLineStrings	bool	true	Triple-quote format for long strings.
MultiLineStringThreshold	int	80	Character count above which a string becomes multi-line.
UseEnhancedMetadata	bool	true	Full per-property metadata (description + purpose + constraints + examples + navigation) vs compact single-line form.
OmitDefaultValues	bool	true	Skip properties whose value equals default(T) / null / 0 / false.
WriteTypeNames	bool	true	Emit the type name before { on @data objects.
MaxExampleStringLength	int	50	Truncate example values in @types beyond this length.

Inherited from AcSerializerOptions

Option	Type	Notes
MaxDepth	byte	Recursion guard; when exceeded, null is emitted.
ReferenceHandling	ReferenceHandlingMode	None / OnlyId / All — required for circular or shared-reference graphs.
SerializerType	AcSerializerType	Fixed to Toon.

ToonSerializationMode enum

public enum ToonSerializationMode : byte
{
    Full     = 0,  // @meta + @types + @data (default)
    MetaOnly = 1,  // @meta + @types only
    DataOnly = 2,  // @data only
}

Presets

Each preset is a fresh instance (static property with new expression — no shared state between retrievals).

Default

Mode = Full, UseMeta = true, UseIndentation = true,
OmitDefaultValues = true, WriteTypeNames = true

First-time serialization with full context for the LLM.

MetaOnly

Mode = MetaOnly, UseMeta = true, UseIndentation = true,
UseInlineComments = true

Send schema once at conversation start. UseInlineComments = true adds clarity since no @data follows.

DataOnly

Mode = DataOnly, UseMeta = false, UseIndentation = true,
OmitDefaultValues = true, WriteTypeNames = true

Subsequent sends once the LLM already has the schema.

Compact

Mode = DataOnly, UseMeta = false, UseIndentation = true,
OmitDefaultValues = true, WriteTypeNames = false,
ReferenceHandling = None

Data-only, no type names, no reference tracking. Note: UseIndentation = true here — truly token-minimal output requires manually setting UseIndentation = false on a custom options instance.

Verbose

Mode = Full, UseMeta = true, UseIndentation = true,
UseInlineTypeHints = true, UseInlineComments = true,
OmitDefaultValues = false, WriteTypeNames = true

Debugging / documentation — every hint turned on, defaults included. Bloats tokens; avoid for production LLM contexts.

Factory helpers

AcToonSerializerOptions.WithMaxDepth(10)
AcToonSerializerOptions.WithoutReferenceHandling()

Short-hand for common one-off customizations.

Custom options

All properties are init; — assemble once per serialization call:

var opts = new AcToonSerializerOptions
{
    Mode = ToonSerializationMode.Full,
    UseIndentation = false,         // tight token-minimal output
    ShowCollectionCount = true,
    UseMultiLineStrings = false,    // keep long strings inline
    OmitDefaultValues = true,
    MaxDepth = 20
};
string toon = AcToonSerializer.Serialize(value, opts);

Public API overloads

Method	Purpose
Serialize<T>(T value)	Default options.
Serialize<T>(T value, AcToonSerializerOptions)	Custom options.
Serialize<T>(T value, string domainDescription, AcToonSerializerOptions)	Adds context = "..." line to @meta.
SerializeTypeMetadata<T>() / SerializeTypeMetadata(Type)	Schema only — uses MetaOnly internally.
SerializeMetadata(IEnumerable<Type>)	Schema for multiple types (no instance required).
SerializeMetadata(params Type[])	Schema for multiple types (params syntax).
SerializeMetadata(string domainDescription, params Type[])	Multi-type schema with domain context in @meta.

Picking a preset / customization

Scenario	Choice
First prompt to an LLM in a new conversation	Default
Send schema once, many data round-trips	MetaOnly then DataOnly
Token-minimal streaming after schema is established	Custom: Mode = DataOnly + UseIndentation = false + WriteTypeNames = false
Debugging, local inspection	Verbose
Cyclic object graph (entity with backrefs)	Any preset, but ensure ReferenceHandling = OnlyId or All on a custom options instance