Package versions and protocol versions are different. Published package scope: runtime DevOp.Toon 0.3.0, Core 0.2.0, API 0.2.0, and Client 0.2.0. Runtime 0.3.0 supports these protocol selections:
| TOON protocol | ToonProtocolVersion |
Write / serialize | Read / deserialize |
|---|---|---|---|
| Official 3.0 | V3_0 |
Yes | Yes |
| Official 4.0 | V4_0 |
Yes | Yes |
| Official 4.1 | V4_1 |
Yes | Yes |
| Official 4.2 | V4_2 |
Yes | Yes |
| Official 4.3 | V4_3 |
Yes | Yes |
| Official 4.4 | V4_4 |
Yes — default | Yes |
| Legacy custom | CustomLegacy |
Yes | Yes |
| Custom 4.4 | CustomV4_4 |
Yes | Yes |
| Automatic detection | Auto |
No | Yes — default; ambiguous input requires a hint |
The official 3.0 entry means 3.0, not all 3.x releases. Pinned fixture provenance is 3.0.0, 4.0.0, 4.1.3, 4.2.1, 4.3.0, and 4.4.0. These fixture tags identify the checked-in specification test inputs; they are not NuGet versions or a promise of support for every release in a major series.
Runtime, Core, and Client target .NET Standard 2.0 and .NET 8, 9, and 10. API targets .NET 8 and 10. Framework targets are independent of the TOON wire protocol.
Select the enum when serializing. Supply it when decoding known legacy or ambiguous input. Custom formats require compatible readers at both ends. Version selection and migration guide · Pinned fixture provenance.
This document summarizes the TOON format as used by this repository and explains the object-array Columnar behavior implemented by this .NET library.
Primary references:
This file is intentionally short and implementation-oriented. For the canonical format definition, use the official TOON site.
TOON is a compact text format for structured data. At a high level:
key: value pairs[3]:{id,name}The format is designed to reduce repeated field names compared with JSON, especially for arrays of similarly shaped objects.
Common forms used by the protocol:
name: Ada
active: true
count: 3
Object with nested members:
user:
id: 1
name: Ada
Primitive array:
tags[3]: red,green,blue
Root primitive array:
[3]: x,y,z
Tabular array of objects:
items[2]{id,name}:
1,Ada
2,Bob
Array of arrays:
pairs[2]:
- [2]: 1,2
- [2]: 3,4
Empty array:
items[0]:
From the official syntax cheat sheet, strings must be quoted when they would otherwise be ambiguous or syntactically active. In practice that includes values that:
null, or numbers:, ", \, [, ], {, }Examples:
version: "123"
enabled: "true"
note: "hello, world"
name: ""
TOON supports different delimiters for inline primitive arrays and tabular rows. This library exposes that through ToonEncodeOptions.Delimiter.
Examples:
a,b,cThe active delimiter also affects quoting. A string containing the active delimiter must be quoted.
The dedicated official vs custom 4.4 guide explains which features both profiles share, what row spills add, and how to use custom output without omitting values. It includes generated examples and a runnable published-package sample.
Official modes select tabular output for eligible uniform rows and list output for richer shapes. Official 4.4 supports nested header groups for uniform nested objects. An array-valued column prevents official tabular encoding.
CustomLegacy preserves the earlier custom columnar/spill profile. CustomV4_4 combines nested header groups with row/keyed spills, retaining scalar table columns even when rows contain nested collections. ToonObjectArrayLayout.Columnar requires an explicitly selected custom protocol. Both custom formats require compatible readers.
JSON input:
{
"items": [
{
"status": "active",
"count": 2,
"users": [
{ "id": 1, "name": "Ada" },
{ "id": 2, "name": "Bob" }
],
"tags": ["a", "b", "c"]
}
]
}
Columnar output in this library:
items[1]{status,count}:
active,2
users[2]{id,name}:
1,Ada
2,Bob
tags[3]: a,b,c
This is not plain tabular output and not plain list output. It is a mixed layout:
Encoding defaults to official V4_4, comma delimiters, key folding off, one-space indentation, and both omission options false. Runtime DI encoding also defaults to one space; decoder options default to two spaces. API registration aligns both widths at two spaces. With explicit decode options, match the producer's indentation or detect options using the supplied version hint.
using DevOp.Toon;
using DevOp.Toon.Core;
var encode = new ToonEncodeOptions
{
ProtocolVersion = ToonProtocolVersion.CustomV4_4,
IgnoreNullOrEmpty = false,
ExcludeEmptyArrays = false
};
Custom profiles default both omission options to true unless explicitly overridden. Set both false when null, empty-string, and empty-array distinctions must be retained. CustomLegacy is the migration choice for the previous custom wire format; CustomV4_4 is a separate custom format. Automatic decoding does not guess when interpretations differ.
Columnar is useful when an array of objects has:
It preserves more of TOON's tabular compactness while still supporting richer row payloads.
In practical terms, it is meant to reduce repeated field names in partially uniform collections without forcing everything into list-style nested objects.
When documenting or discussing TOON behavior in this repository, distinguish between:
toonformat.devColumnarColumnar is an encoder policy exposed by this implementation. It is not just a syntax example; it changes how arrays of objects are chosen for output.