Custom 4.4 keeps shared table columns when records also contain collections or fields that vary
between rows. This reduces repeated field names without requiring you to flatten your models.
Choose it for compatible producers and consumers that exchange nested catalogs, stock records,
audit histories or similar collections. Choose official 4.4 when consumers require the standard grammar.
This guide covers DevOp.Toon 0.3.0, Core 0.2.0, API 0.2.0 and Client 0.2.0.
4.4 is a protocol version; it is separate from the NuGet package version.
Official 4.4 already supports nested header groups and keyed tables. Those features are shared
by both profiles. The custom extension addresses rows that cannot fit a complete shared header:
it keeps the eligible columns and writes the remaining fields one level beneath their owning row.
These fields are called row spills.
| Behavior | Official V4_4 |
CustomV4_4 |
|---|---|---|
| Uniform scalar rows | Shared table header | Shared table header |
| Uniform nested objects | Nested header groups | Nested header groups |
| Uniform object-valued maps | Keyed tables | Keyed tables |
| Rows containing array-valued fields | List form | Shared columns plus row spills, when eligible |
| Rows with different fields or irregular nested objects | List/nested form | Shared columns plus row spills, when eligible |
| Keyed entries with collections or irregular fields | Nested object form | Keyed table plus entry spills, when eligible |
| No eligible shared columns | List/nested form | List/nested form |
| Omit null/empty values by default | Both omission options false |
Both omission options true |
| Transport version value | 4.4 |
custom-4.4 |
Official grammar and examples are documented in the
TOON format overview.
The row-spill extension requires a custom-compatible reader at both ends.
The following output is generated by the runnable sample,
with two-space indentation and both omission options disabled. Both versions preserve the same
DTO values. Each product has an Id, a nested Customer, and a Tags collection.
Official 4.4 uses a list because Tags cannot become a primitive table cell:
[2]:
- Id: 1
Customer:
Name: Ada
Country: IS
Tags[2]: a,b
- Id: 2
Customer:
Name: Bob
Country: GB
Tags[1]: c
Custom 4.4 keeps Id and the uniform Customer group in the header, with Tags below its row:
[2]{Id,Customer{Name,Country}}:
1,Ada,IS
Tags[2]: a,b
2,Bob,GB
Tags[1]: c
The cells follow the header's depth-first order: Id, Customer.Name, Customer.Country.
Spills belong to the preceding row, so the nested collections keep their original owner. This
layout saving does not depend on dropping empty or null values.
If Tags is removed, both profiles can emit the same nested table:
[2]{Id,Customer{Name,Country}}:
1,Ada,IS
2,Bob,GB
For a dictionary of products, custom 4.4 also keeps the entry keys alongside the shared columns:
[2:]{Id,Customer{Name,Country}}:
"sku-1": 1,Ada,IS
Tags[2]: a,b
"sku-2": 2,Bob,GB
Tags[1]: c
The colon in [2:] identifies a keyed table. Each entry row starts with its dictionary key;
its spills appear one indentation level deeper. Keyed tables need at least two nonempty
object-valued entries and at least one eligible shared leaf. Arrays of objects need at least
one eligible shared leaf. Otherwise the encoder uses the ordinary nested/list form.
Install runtime 0.3.0; its Core dependency supplies the enum:
dotnet add package DevOp.Toon --version 0.3.0
This complete console example uses explicit versions and matching indentation:
using DevOp.Toon;
using DevOp.Toon.Core;
Product[] products =
[
new() { Id = 1, Customer = new() { Name = "Ada", Country = "IS" }, Tags = ["a", "b"] },
new() { Id = 2, Customer = new() { Name = "Bob", Country = "GB" }, Tags = ["c"] }
];
var text = ToonEncoder.Encode(products, new ToonEncodeOptions
{
ProtocolVersion = ToonProtocolVersion.CustomV4_4,
Indent = 2,
IgnoreNullOrEmpty = false,
ExcludeEmptyArrays = false
});
var decoded = ToonDecoder.Decode<Product[]>(text, new ToonDecodeOptions
{
ProtocolVersion = ToonProtocolVersion.CustomV4_4,
Indent = 2
})!;
Console.WriteLine(text);
Console.WriteLine(decoded[0].Customer.Name);
public sealed class Product
{
public int Id { get; set; }
public Customer Customer { get; set; } = new();
public string[] Tags { get; set; } = [];
}
public sealed class Customer
{
public string Name { get; set; } = "";
public string Country { get; set; } = "";
}
Custom modes default IgnoreNullOrEmpty and ExcludeEmptyArrays to true. Set both explicitly
to false when null, empty-string and empty-array distinctions matter. Enabling omissions is a
separate choice that can change the represented data. Typed decoding preserves the fields in
your supported DTO schema; use DOM/JSON paths when retaining unmodeled JSON members matters.
Changing both enum selections to V4_4 uses the official grammar. The encoder chooses the
eligible layout; selecting custom does not force every collection into a table.
The full sample uses published NuGet packages, prints both
layouts and checks complete typed round trips, dictionary keys, nulls and empty values.
With DevOp.Toon.API 0.2.0, configure MVC response encoding while leaving request decoding
at Auto, so a supplied request X-Toon-Version can select the body grammar:
using DevOp.Toon.API;
using DevOp.Toon.Core;
builder.Services.AddControllers().AddToon(options =>
{
options.Indent = 2;
options.Encode.ProtocolVersion = ToonProtocolVersion.CustomV4_4;
options.Encode.IgnoreNullOrEmpty = false;
options.Encode.ExcludeEmptyArrays = false;
});
builder is your ASP.NET Core application's existing builder. This is MVC formatter registration;
map your controllers in the application as usual.
With DevOp.Toon.Client 0.2.0, request custom responses independently of the request format:
using DevOp.Toon;
using DevOp.Toon.Client;
using DevOp.Toon.Core;
builder.Services.AddToonClient(options =>
{
options.BaseAddress = new Uri("https://api.example.com/");
options.EncodeOptions = new ToonEncodeOptions
{
ProtocolVersion = ToonProtocolVersion.V4_4,
Indent = 2
};
options.ResponseEncodeOverrides = new ToonResponseEncodeOverrideOptions
{
ProtocolVersion = ToonProtocolVersion.CustomV4_4,
Indent = 2,
IgnoreNullOrEmpty = false,
ExcludeEmptyArrays = false
};
});
For raw HTTP clients, the corresponding request headers are:
Content-Type: application/toon
Accept: application/toon
X-Toon-Version: 4.4
X-Toon-Option-ProtocolVersion: custom-4.4
X-Toon-Option-Indent: 2
X-Toon-Option-IgnoreNullOrEmpty: false
X-Toon-Option-ExcludeEmptyArrays: false
Here the request body is official 4.4, while the requested response is custom 4.4. A TOON response
declares its actual body version in X-Toon-Version. To send a custom request body as well, set
the client's EncodeOptions.ProtocolVersion to CustomV4_4 and explicitly disable its two
omission options; raw HTTP senders use X-Toon-Version: custom-4.4 with a matching body.
For GET requests without a body, omit the body headers (Content-Type and X-Toon-Version).
Automatic decoding can recognize distinctive custom syntax, but many documents are valid under
multiple versions. Use the known body version or transport metadata; detection does not prove
the producer's exact version. Auto is decode-only. Do not add a version directive to TOON text.
The 6 November 2026 published-package benchmark measured all 2,051 normalized product DTOs
on .NET 10.0.13, with omissions disabled in both profiles:
| Metric | Official 4.4 | Custom 4.4 |
|---|---|---|
| UTF-8 payload bytes | 5,959,545 | 2,939,907 |
| Bytes allocated during decoding | 27,730,160 | 10,242,568 |
| Encode median, ms | 28.23 | 19.98 |
| Explicit decode median, ms | 62.35 | 43.51 |
On this dataset, custom output contains 50.7% fewer UTF-8 bytes and decoding allocates
63.1% less memory. Both profiles preserve the same complete normalized DTO model.
The measurement uses 30 warmups and 50 samples, tiered compilation disabled, and no forced GC
inside timed samples. Profiles ran sequentially in one process, so shared-pool history can
affect timing and allocation observations. This is a measured workload, not a general speed guarantee.
The DTO projection excludes the original JSON's Publication member; a separate raw-DOM checker
covers that member. These results measure typed serialization, not full raw-JSON preservation,
HTTP latency, retained memory or LLM token counts. Smaller UTF-8 output does not establish a
specific token saving. Compression results also need their own comparison.
Compared with legacy custom, a separate fresh-process old/new pair found custom 4.4 decoded
17.0% slower, allocated 42.1% less memory during decoding, and produced 3.9% fewer bytes.
The older encoder also has a reported numeric precision defect. These are different comparisons;
custom 4.4 is not a speed upgrade for every existing workload.
See published-package results and reproduction for the complete
method, provenance and fidelity limits. For performance budgets, run the equivalent profiles in
isolated fresh processes on your own data, including explicit and automatic decoding separately.
Use official 4.4 for standard TOON interchange or when all rows already fit its tables.
Use custom 4.4 when shared scalar/nested columns coexist with collections or irregular fields,
and compatible readers are under your control. Use CustomLegacy when you need the earlier
custom wire behavior; custom 4.4 is a separate format, with literal dotted keys and the v4 grammar.
Supported versions and migration ·
Published benchmark results ·
Runnable custom 4.4 sample