TOON Spec Conformance
ToonNet implements TOON spec v4.4
(toon-format/spec, tag v4.4.0). This page describes how conformance is verified and documents the
implementation-defined behavior that the spec requires implementations to document. For the format itself,
read the spec; this page does not restate it.
ToonNet Implementation Status
Measured conformance
ToonNet runs the official conformance fixtures of TOON spec v4.4 in CI
(tests/ToonNet.Tests/SpecCompliance/Fixtures/v4.4). Cases that do not pass would be listed in
tests/ToonNet.Tests/SpecCompliance/KnownNonConformance.txt; CI fails if a listed case starts passing without being
removed, so the list always reflects the current state. It is empty.
| Fixture set | Cases | Passing |
|---|---|---|
| Encode | 160 | 160 |
| Decode | 404 | 404 |
| Total | 564 | 564 (100%) |
Every part of the spec is implemented, including comment lines (§5.1), nested field groups (§9.3), keyed tabular
objects (§9.5) and the five non-strict recoveries (§14.4). Spec v4 has no optional features (key folding and path
expansion were removed), so dotted keys such as user.name are always literal keys.
Compatibility with the official .NET library
tests/ToonNet.Compatibility.Tests runs with every build against
Toon.Format, the official .NET implementation: both pass all 564
fixtures, encode thousands of random JSON documents to identical text and read each other's output. The differences
that remain are in how .NET values map to the data model (see ToonNet vs Toon.Format):
ToonNet writes enum names and keeps every digit of decimal and ulong values.
Options
| Spec option | ToonNet | Default |
|---|---|---|
indentSize | ToonOptions.IndentSize (1–100) | 2 |
delimiter | ToonOptions.Delimiter (,, \t, |) | , |
strict | ToonOptions.StrictMode | true |
ToonOptions.MaxDepth (default 100) additionally limits nesting when encoding and decoding; nested field groups
count as levels.
Implementation-defined behavior
Host type normalization (§3)
The mapping from .NET types to the TOON data model is documented in
Type System – .NET Type Mapping. In short:
enums are written by name, DateTime/DateTimeOffset as ISO 8601 strings without trailing zeros in the fraction
of a second (2026-01-02T03:04:05Z), Guid, TimeSpan, DateOnly and TimeOnly as strings, dictionaries as
objects and other collections as arrays. NaN and ±Infinity are encoded as null. A string with an unpaired surrogate
cannot be represented and throws ToonEncodingException. Custom mappings use IToonConverter / [ToonConverter].
Numbers (§2, §4)
- Numeric domain:
ToonNumberholds an IEEE 754doubleand, when the value is exactly representable, adecimal(ToonNumber.DecimalValue, 28–29 significant digits, |n| < 7.9e28). - Encoding: values with 1e-6 ≤ |n| < 1e21 are written in plain decimal form; others use exponent form with a
lowercase
eand explicit sign (1e-7,1.5e+21), as §2 recommends.doublevalues use the shortest representation that round-trips;decimal,longandulongvalues keep all their digits. Integers outside thedecimalrange (BigInteger,Int128,UInt128) are written as quoted decimal strings (lossless). - Decoding / out-of-range policy: tokens matching the JSON number grammar become numbers. A number that fits in a
decimalkeeps its exact value; otherwise it is approximated as adouble. A numeric token that overflowsdouble(for example1e400) decodes as a string, not as infinity. When binding to .NET integer types, fractions and out-of-range values throwToonSerializationExceptionrather than being truncated. -0decodes as the number zero:0in integers,decimalandobject, negative zero indoubleandfloat(asdouble.Parseand System.Text.Json give it). It is written as0.
Key order and keys (§2, §15)
ToonObject keeps keys in document order, and objects are bound in that order. Every key, including __proto__, is
an ordinary key. Keys that differ only in Unicode normalization are distinct.
Byte input (§4)
Streams and files are decoded as UTF-8; ill-formed UTF-8 is an error (ToonParseException), never U+FFFD. A
byte-order mark at the start is removed; one anywhere else is content.
Non-strict mode (§14.4)
Non-strict mode applies exactly the five recoveries of §14.4 and reports every other error like strict mode:
- declared counts (
[N]) are not checked; every value, item, row and entry row is read, - duplicate keys and repeated field names resolve by last-write-wins (the key keeps its first position),
- a line's depth is its tabs plus
floor(spaces / IndentSize), and a line of only spaces and tabs is blank, - blank lines inside arrays and keyed objects are ignored,
- a nested scope whose first line is indented too deep takes that depth.
Row widths are checked in both modes.
Encoder choices
- The form follows the value's shape (§9): uniform objects use the tabular form, with nested field groups for uniform
nested objects; objects (and dictionaries) of at least two uniform objects use the keyed tabular form; other arrays
use the inline or list form. The serializer and generated code write the same text as encoding the
ToonValuetree. - Empty arrays use the canonical
key: []/[]forms (§9.1); inner arrays of list items use[0]:(§9.2). - The first field of a list-item object is written on the hyphen line (§10).
- Strings are quoted per §7.2 (only SP and HTAB count as whitespace) and escaped per §7.1; other control characters
use lowercase
\uXXXX. A root string starting with U+FEFF is quoted. - Output has LF line endings, no comments, no blank lines, no trailing spaces and no trailing newline.
Limits and errors
- Errors are reported as
ToonParseExceptionwith line and column. Deserialization errors (type mismatches) areToonSerializationExceptionwith the path of the value, e.g.$.items[2].price. - Nesting beyond
MaxDepth, or beyond the available stack space, is rejected with an exception instead of overflowing the stack. - A declared length does not reserve memory beyond the lines that follow it (§15).
Updating to a newer spec version
- Replace
tests/ToonNet.Tests/SpecCompliance/Fixtures/<version>with the fixtures of the new tag and updateFixtureVersionandTargetSpecVersioninSpecFixtureConformanceTests. - Regenerate
KnownNonConformance.txtwithTOONNET_WRITE_NONCONFORMANCE=<path>and fix the listed cases. - Update
docs/TOON_SPEC_COMPLIANCE.md,website/docs/toon-spec.mdand the README badge.