This was generated by AI during triage.
Spec v4.0.0 shipped today (toon-format/spec@v4.0.0, @toon-format/spec@4.0.0) and the TypeScript reference (toon-format/toon@v4.0.0) is already on it. This issue tracks each known port moving from v3.3.x to v4.0. Not urgent – v3 documents still decode identically under v4, and the one wire-visible producer change is opt-in per object. Comment below or link your upgrade PR and I'll tick boxes.
The full delta with § references and migration steps is in the v4.0 section of CHANGELOG.md. Short version below.
What actually breaks a port
- Remove key folding / path expansion – options
keyFolding, flattenDepth, expandPaths and their fixtures are gone. Dotted keys are single literal keys (already the v3 default with folding off), so no wire change.
- Decode-side comment lines (§5.1): strip every line whose first non-space char is
# in a pre-pass, strict and non-strict alike, before any counting or classification.
- Encoder must quote values equal to or starting with
# (§7.2), and quote leading-plus numeric-likes so "+1" round-trips.
- Normative number grammar (§4): a token is a number only if it matches
/^-?[0-9]+(?:\.[0-9]+)?(?:e[+-]?[0-9]+)?$/i. No delegating to a host parser – .5, 1., +5, 0x10, 1_000, Infinity, NaN are strings.
- New tabular header forms – decoders should ship these first:
- Nested field groups (§9.3):
orders[2]{id,customer{name,country},total}:, rows stay flat, width check is against leaf-field count.
- Keyed tabular objects (§9.5):
users[2:]{age,city}: with one alice: 30,Berlin entry row each; the colon after [N marks it keyed, fields segment required. This is the one encoder-visible output change – any object with ≥2 entries of one uniform shape now encodes keyed.
- Strict-mode surface: depth jumps error (§8/§14.2); blank line inside an array/keyed span errors (§12); keyless-header positions and fields-bearing-header inline content are constrained (§6); over-indented orphan and trailing-root lines must error, not be silently dropped.
- Decode input: strip a trailing CR per line (accept CRLF); byte-input decoders decode UTF-8 and error on ill-formed sequences in strict mode.
Conformance suite (tests/fixtures/)
- New:
decode/comments.json, decode/objects-keyed.json, encode/objects-keyed.json. Removed: encode/key-folding.json, decode/path-expansion.json.
- Fixture option
indent renamed to indentSize.
- Per-file
version baseline is "4.0"; per-test minSpecVersion overrides it – gate tests above the version you target. tests/README.md classifies non-strict cases by requirement level; error tests carry shouldError: true with no expected message.
- Please declare the spec version you target (§13, e.g.
toon-spec: 4.0).
Suggested order – decoders first (comment pre-pass → line classification + number grammar → CRLF/UTF-8 → nested + keyed headers → strict surface → drop expandPaths), then encoder (drop folding → # and leading-plus quoting → keyed emission → nested emission → swap fixtures). Shipping decoder support ahead of the encoder is fine and encouraged – it's the intended rollout so v4 producers don't break v3 consumers.
Ports (tick when on v4.0; link your PR)
Official
Community
Maintainer of a port not listed, or one that shouldn't be? Comment and I'll fix the list.
Spec v4.0.0 shipped today (
toon-format/spec@v4.0.0,@toon-format/spec@4.0.0) and the TypeScript reference (toon-format/toon@v4.0.0) is already on it. This issue tracks each known port moving from v3.3.x to v4.0. Not urgent – v3 documents still decode identically under v4, and the one wire-visible producer change is opt-in per object. Comment below or link your upgrade PR and I'll tick boxes.The full delta with
§references and migration steps is in the v4.0 section ofCHANGELOG.md. Short version below.What actually breaks a port
keyFolding,flattenDepth,expandPathsand their fixtures are gone. Dotted keys are single literal keys (already the v3 default with folding off), so no wire change.#in a pre-pass, strict and non-strict alike, before any counting or classification.#(§7.2), and quote leading-plus numeric-likes so"+1"round-trips./^-?[0-9]+(?:\.[0-9]+)?(?:e[+-]?[0-9]+)?$/i. No delegating to a host parser –.5,1.,+5,0x10,1_000,Infinity,NaNare strings.orders[2]{id,customer{name,country},total}:, rows stay flat, width check is against leaf-field count.users[2:]{age,city}:with onealice: 30,Berlinentry row each; the colon after[Nmarks it keyed, fields segment required. This is the one encoder-visible output change – any object with ≥2 entries of one uniform shape now encodes keyed.Conformance suite (
tests/fixtures/)decode/comments.json,decode/objects-keyed.json,encode/objects-keyed.json. Removed:encode/key-folding.json,decode/path-expansion.json.indentrenamed toindentSize.versionbaseline is"4.0"; per-testminSpecVersionoverrides it – gate tests above the version you target.tests/README.mdclassifies non-strict cases by requirement level; error tests carryshouldError: truewith no expected message.toon-spec: 4.0).Suggested order – decoders first (comment pre-pass → line classification + number grammar → CRLF/UTF-8 → nested + keyed headers → strict surface → drop
expandPaths), then encoder (drop folding →#and leading-plus quoting → keyed emission → nested emission → swap fixtures). Shipping decoder support ahead of the encoder is fine and encouraged – it's the intended rollout so v4 producers don't break v3 consumers.Ports (tick when on v4.0; link your PR)
Official
toon-format/toon-javatoon-format/ToonFormat.jltoon-format/toon-pythontoon-format/toon-rusttoon-format/toon-swifttoon-format/toon-dotnettoon-format/toon-darttoon-format/toon-goCommunity
Eacaw/ApexToonUsboKirishima/TOONcmohammadraziei/ctoonCysharp/ToonEncodervadelabs/toonmamantoha/toon-crystalernestoalconada/delphi-toonkentaro/toon_exaxelbellec/toon_codecalpkeskin/gotoonjdereg/json-iolukelast/ktoonmischasigtermans/laravel-toonthalesgelinger/toon.nvimdavesnx/ocaml-toonytnobody/p5-Data-TOONHelgeSverre/toon-phpalesanfra/toonslaresbernardo/toonandrepcg/toon-rubyvim89/toon4sLatentEvals/toon-zigMaintainer of a port not listed, or one that shouldn't be? Comment and I'll fix the list.