@toon-format/spec 2.0.0 → 2.1.0

package/CHANGELOG.md

@@ -5,87 +5,83 @@ All notable changes to the TOON specification will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.1] - 2025-11-23
+
+### Changed
+
+- Canonical encoding for objects as list items (§10):
+  - Encoders SHOULD emit `- key[N]{fields}:` only when the list-item object has exactly one field and that field is a tabular array.
+  - In all other cases, encoders SHOULD emit a bare `-` line and place all fields at depth +1; tabular array headers then appear at depth +1 and their rows at depth +2.
+
 ## [2.0] - 2025-11-10
 
 ### Breaking Changes
 
-- **Removed:** Length marker (`#`) prefix in array headers has been completely removed from the specification
-- The `[#N]` format is no longer valid syntax. All array headers MUST use `[N]` format only
-- Encoders MUST NOT emit `[#N]` format
-- Decoders MUST NOT accept `[#N]` format (breaking change from v1.5)
+- Removed `[#N]` length-marker syntax in array headers; `[N]` is now the only valid format.
+- Encoders MUST NOT emit `[#N]`; decoders MUST reject it.
 
 ### Removed
 
-- All references to length marker from terminology (§1.4), header syntax (§6), ABNF grammar, conformance requirements (§13.2), and parsing helpers (Appendix B)
-- `lengthMarker` encoder option removed from all implementations
-- Length marker test fixtures removed
+- The `lengthMarker` encoder option and any CLI flags exposing it.
 
 ### Migration from v1.5
 
-- Update decoder implementations to reject `[#N]` syntax
-- Convert any existing `.toon` files using `[#N]` format to `[N]` format
-- Remove `lengthMarker` option from encoder configurations
-- Remove `--length-marker` CLI flags if present
+- Update decoders to reject `[#N]` syntax.
+- Convert existing `.toon` files using `[#N]` to `[N]`.
+- Remove `lengthMarker` configuration and CLI options.
 
 ## [1.5] - 2025-11-08
 
 ### Added
 
-- Optional key folding for encoders: `keyFolding="safe"` mode with `flattenDepth` control to collapse single-key object chains into dotted-path notation (§13.4)
-- Optional path expansion for decoders: `expandPaths="safe"` mode to split dotted keys into nested objects, with conflict resolution tied to `strict` option (§13.4, §14.5)
-- IdentifierSegment terminology and path separator definition (fixed to `"."` in v1.5) (§1.9)
-- Deep-merge semantics for path expansion: recursive merge for objects, error on conflict when `strict=true`, last-write-wins (LWW) when `strict=false` (§13.4)
+- Optional key folding for encoders: `keyFolding="safe"` with `flattenDepth` to collapse single-key object chains into dotted paths (§13.4).
+- Optional path expansion for decoders: `expandPaths="safe"` to split dotted keys into nested objects with deep-merge semantics and conflict handling tied to `strict` (§13.4, §14.5).
+- IdentifierSegment terminology and fixed `"."` path separator for safe folding/expansion (§1.9).
 
 ### Changed
 
-- Both new features default to OFF and are fully backward-compatible
-- Safe-mode folding requires IdentifierSegment validation, collision avoidance, and no quoting
+- Safe-mode folding requires IdentifierSegment-only segments, no path separator in segments, no quoting, and collision avoidance.
+- Both features default to `off` and are backward-compatible.
 
 ## [1.4] - 2025-11-05
 
 ### Changed
 
-- Removed JavaScript-specific normalization details from specification; replaced with language-agnostic requirements (Section 3)
-- Defined canonical number format for encoders: no exponent notation, no trailing zeros, no leading zeros except "0" (Section 2)
-- Clarified decoder handling of exponent notation and out-of-range numbers (Section 2)
-- Expanded `\w` regex notation to explicit character class `[A-Za-z0-9_]` for cross-language clarity (Section 7.3)
-- Clarified non-strict mode tab handling as implementation-defined (Section 12)
+- Generalized normalization rules and defined canonical number format for encoders (no exponent notation, no trailing zeros, no leading zeros except `"0"`), plus decoder handling of exponent forms and out-of-range numbers (§2-§3).
+- Replaced `\w` with explicit `[A-Za-z0-9_]` in key regexes for cross-language clarity (§7.3).
+- Clarified non-strict mode tab handling as implementation-defined (§12).
 
 ### Added
 
-- Appendix G: Host Type Normalization Examples with guidance for Go, JavaScript, Python, and Rust implementations
+- Appendix G with host-type normalization examples for Go, JavaScript, Python, and Rust.
 
 ## [1.3] - 2025-10-31
 
 ### Added
 
-- Numeric precision requirements: JavaScript implementations SHOULD use `Number.toString()` precision (15-17 digits), all implementations MUST preserve round-trip fidelity (Section 2)
-- RFC 5234 core rules (ALPHA, DIGIT, DQUOTE, HTAB, LF, SP) to ABNF grammar definitions (Section 6)
+- Numeric precision requirements: JavaScript implementations SHOULD use `Number.toString()` precision (15–17 digits); all implementations MUST preserve round-trip fidelity (§2).
+- RFC 5234 core rules (ALPHA, DIGIT, DQUOTE, HTAB, LF, SP) to ABNF grammar definitions (§6).
 
 ## [1.2] - 2025-10-29
 
 ### Changed
 
-- Clarified delimiter scoping behavior between array headers
-- Tightened strict-mode indentation requirements: leading spaces MUST be exact multiples of indentSize; tabs in indentation MUST error
-- Defined blank-line and trailing-newline decoding behavior with explicit skipping rules outside arrays
-- Clarified hyphen-based quoting: "-" or any string starting with "-" MUST be quoted
-- Clarified BigInt normalization: values outside safe integer range are converted to quoted decimal strings
-- Clarified row/key disambiguation: uses first unquoted delimiter vs colon position
+- Tightened delimiter scoping, indentation, blank-line handling, and hyphen-based quoting rules (§11-§12).
+- Clarified BigInt normalization (out-of-range values → quoted decimal strings) and row/key disambiguation (first unquoted delimiter vs colon) (§2, §9.3).
 
 ## [1.1] - 2025-10-29
 
 ### Added
 
-- Strict-mode rules
-- Delimiter-aware parsing
-- Decoder options (indent, strict)
+- Strict-mode rules.
+- Delimiter-aware parsing.
+- Decoder options (`indent`, `strict`).
 
 ## [1.0] - 2025-10-28
 
 ### Added
 
-- Initial specification release
-- Encoding normalization rules
-- Decoding interpretation guidelines
-- Conformance requirements
+- Initial specification release.
+- Encoding normalization rules.
+- Decoding interpretation guidelines.
+- Conformance requirements.

package/README.md

@@ -1,16 +1,16 @@
 # TOON Format Specification
 
-[![SPEC v2.0](https://img.shields.io/badge/spec-v2.0-lightgrey)](./SPEC.md)
-[![Tests](https://img.shields.io/badge/tests-340-green)](./tests/fixtures/)
+[![SPEC v2.1](https://img.shields.io/badge/spec-v2.1-lightgrey)](./SPEC.md)
+[![Tests](https://img.shields.io/badge/tests-344-green)](./tests/fixtures/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
 
-This repository contains the official specification for **Token-Oriented Object Notation (TOON)**, a compact, human-readable serialization format designed for passing structured data to Large Language Models with significantly reduced token usage.
+This repository contains the official specification for **Token-Oriented Object Notation (TOON)**, a compact, human-readable encoding of the JSON data model for LLM prompts. It provides a lossless serialization of the same objects, arrays, and primitives as JSON, but in a syntax that minimizes tokens and makes structure easy for models to follow.
 
 ## 📋 Specification
 
 [→ Read the full specification (SPEC.md)](./SPEC.md)
 
-- **Version:** 2.0 (2025-11-10)
+- **Version:** 2.1 (2025-11-23)
 - **Status:** Working Draft
 - **License:** MIT
 
@@ -18,38 +18,76 @@ The specification includes complete grammar (ABNF), encoding rules, validation r
 
 ## What is TOON?
 
-**Token-Oriented Object Notation** is a compact, human-readable serialization format designed for passing structured data to Large Language Models with significantly reduced token usage. It's intended for LLM input, not output.
+> [!IMPORTANT]
+> For a high-level overview of TOON, its features and benefits, design goals, and comparisons to other formats, see the [`toon-format/toon` repository](https://github.com/toon-format/toon).
 
-TOON's sweet spot is **uniform arrays of objects** – multiple fields per row, same structure across items. It borrows YAML's indentation-based structure for nested objects and CSV's tabular format for uniform data rows, then optimizes both for token efficiency in LLM contexts. For deeply nested or non-uniform data, JSON may be more efficient.
+## Serialization Example
 
-**Key Features:**
-
-- 💸 **Token-efficient:** typically 30–60% fewer tokens than JSON
-- 🤿 **LLM-friendly guardrails:** explicit lengths and fields enable validation
-- 🍱 **Minimal syntax:** removes redundant punctuation (braces, brackets, most quotes)
-- 📐 **Indentation-based structure:** like YAML, uses whitespace instead of braces
-- 🧺 **Tabular arrays:** declare keys once, stream data as rows
-
-## Quick Example
-
-**JSON:**
+<table>
+<tr>
+<th>JSON</th>
+<th>TOON</th>
+</tr>
+<tr>
+<td>
 
 ```json
 {
-  "users": [
-    { "id": 1, "name": "Alice", "role": "admin" },
-    { "id": 2, "name": "Bob", "role": "user" }
+  "context": {
+    "task": "Our favorite hikes together",
+    "location": "Boulder",
+    "season": "spring_2025"
+  },
+  "friends": ["ana", "luis", "sam"],
+  "hikes": [
+    {
+      "id": 1,
+      "name": "Blue Lake Trail",
+      "distanceKm": 7.5,
+      "elevationGain": 320,
+      "companion": "ana",
+      "wasSunny": true
+    },
+    {
+      "id": 2,
+      "name": "Ridge Overlook",
+      "distanceKm": 9.2,
+      "elevationGain": 540,
+      "companion": "luis",
+      "wasSunny": false
+    },
+    {
+      "id": 3,
+      "name": "Wildflower Loop",
+      "distanceKm": 5.1,
+      "elevationGain": 180,
+      "companion": "sam",
+      "wasSunny": true
+    }
   ]
 }
 ```
 
-**TOON:**
+</td>
+<td>
 
+```toon
+context:
+  task: Our favorite hikes together
+  location: Boulder
+  season: spring_2025
+
+friends[3]: ana,luis,sam
+
+hikes[3]{id,name,distanceKm,elevationGain,companion,wasSunny}:
+  1,Blue Lake Trail,7.5,320,ana,true
+  2,Ridge Overlook,9.2,540,luis,false
+  3,Wildflower Loop,5.1,180,sam,true
 ```
-users[2]{id,name,role}:
-  1,Alice,admin
-  2,Bob,user
-```
+
+</td>
+</tr>
+</table>
 
 ## Reference Implementation
 
@@ -84,6 +122,22 @@ The [tests/fixtures/](./tests/fixtures/) directory contains **language-agnostic
 
 See [tests/README.md](./tests/README.md) for detailed fixture format and usage instructions.
 
+## Media Type & File Extension
+
+TOON defines a provisional media type (see §18.2 of the specification):
+
+- **Media type:** `text/toon` (provisional, pending IANA registration)
+- **File extension:** `.toon`
+- **Charset:** Always UTF-8
+
+For HTTP usage:
+
+```http
+Content-Type: text/toon
+```
+
+See the full [IANA Considerations section](SPEC.md#18-iana-considerations) for details.
+
 ## Contributing
 
 We welcome contributions to improve the specification! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for:

package/SPEC.md

@@ -2,9 +2,9 @@
 
 ## Token-Oriented Object Notation
 
-**Version:** 2.0
+**Version:** 2.1
 
-**Date:** 2025-11-10
+**Date:** 2025-11-23
 
 **Status:** Working Draft
 
@@ -20,7 +20,7 @@ Token-Oriented Object Notation (TOON) is a line-oriented, indentation-based text
 
 ## Status of This Document
 
-This document is a Working Draft v2.0 and may be updated, replaced, or obsoleted. Implementers should monitor the canonical repository at https://github.com/toon-format/spec for changes.
+This document is a Working Draft v2.1 and may be updated, replaced, or obsoleted. Implementers should monitor the canonical repository at https://github.com/toon-format/spec for changes.
 
 This specification is stable for implementation but not yet finalized. Breaking changes may occur in future major versions.
 
@@ -499,7 +499,15 @@ Decoding:
 For an object appearing as a list item:
 
 - Empty object list item: a single "-" at the list-item indentation level.
-- First field on the hyphen line:
+- Encoding selection (normative):
+  - When an object has **exactly one field** and that field encodes to a tabular array, encoders SHOULD use the compact form with the tabular header on the hyphen line:
+    - Tabular array: - key[N<delim?>]{fields}:
+      - Followed by tabular rows at depth +1 (relative to the hyphen line).
+  - For all other cases (multiple fields, or single non-tabular field), encoders SHOULD emit a bare hyphen on its own line:
+    - Bare hyphen: -
+    - All fields appear at depth +1 under the hyphen line in encounter order, using normal object field rules (Section 8).
+    - When a field is a tabular array, its header appears at depth +1 and its rows at depth +2 (relative to the hyphen line).
+- First field on the hyphen line (legacy encoding, still valid for decoding):
   - Primitive: - key: value
   - Primitive array: - key[M<delim?>]: v1<delim>…
   - Tabular array: - key[N<delim?>]{fields}:
@@ -508,7 +516,7 @@ For an object appearing as a list item:
     - Followed by list items at depth +1.
   - Object: - key:
     - Nested object fields appear at depth +2 (i.e., one deeper than subsequent sibling fields of the same list item).
-- Remaining fields of the same object appear at depth +1 under the hyphen line in encounter order, using normal object field rules.
+  - Remaining fields of the same object appear at depth +1 under the hyphen line in encounter order, using normal object field rules.
 
 Decoding:
 - The first field is parsed from the hyphen line. If it is a nested object (- key:), nested fields are at +2 relative to the hyphen line; subsequent fields of the same list item are at +1.
@@ -894,7 +902,11 @@ This specification does not request IANA registration at this time, as the forma
 
 ### 18.2 Provisional Media Type
 
-The following provisional media type designation is RECOMMENDED for experimental implementations:
+Until IANA registration is completed, implementations SHOULD use:
+- Media type: `text/toon`
+- File extension: `.toon`
+
+Full designation details:
 
 Type name: text
 
@@ -988,12 +1000,15 @@ items[2]:
 Nested tabular inside a list item:
 ```
 items[1]:
-  - users[2]{id,name}:
-    1,Ada
-    2,Bob
+  -
+    users[2]{id,name}:
+      1,Ada
+      2,Bob
     status: active
 ```
 
+Note: Encoders use this format (bare hyphen with all fields indented) for objects with multiple fields. Older encodings may place the first field on the hyphen line; both are valid for decoders.
+
 Delimiter variations:
 ```
 items[2	]{sku	name	qty	price}:
@@ -1218,52 +1233,39 @@ Note: Host-type normalization tests (e.g., BigInt, Date, Set, Map) are language-
 
 ## Appendix D: Document Changelog (Informative)
 
+This appendix summarizes major changes between spec versions. For the complete changelog, see [`CHANGELOG.md`](./CHANGELOG.md) in the specification repository.
+
+### v2.1 (2025-11-23)
+
+- Tightened canonical encoding for objects as list items (§10): bare `-` for multi-field objects, compact `- key[N]{fields}:` only for single-field tabular arrays, to improve visual consistency and LLM readability.
+
 ### v2.0 (2025-11-10)
 
-- Breaking change: Length marker (`#`) prefix in array headers has been completely removed from the specification.
-- The `[#N]` format is no longer valid syntax. All array headers MUST use `[N]` format only.
-- Encoders MUST NOT emit `[#N]` format.
-- Decoders MUST NOT accept `[#N]` format (breaking change from v1.5).
-- Removed all references to length marker from terminology, grammar, conformance requirements, and parsing helpers.
+- Removed `[#N]` length-marker syntax from array headers; `[N]` is now the only valid form.
 
 ### v1.5 (2025-11-08)
 
-- Added optional key folding for encoders: `keyFolding='safe'` mode with `flattenDepth` control (§13.4).
-- Added optional path expansion for decoders: `expandPaths='safe'` mode with conflict resolution tied to existing `strict` option (§13.4).
-- Defined safe-mode requirements for folding: IdentifierSegment validation, no path separator in segments, collision avoidance, no quoting required (§7.3, §13.4).
-- Specified deep-merge semantics for expansion: recursive merge for objects; conflict policy (error in strict mode, LWW when strict=false) for non-objects (§13.4).
-- Added strict-mode error category for path expansion conflicts (§14.5).
-- Both features default to OFF; fully backward-compatible.
+- Added optional key folding (`keyFolding="safe"`) and path expansion (`expandPaths="safe"`) with deep-merge semantics and strict-mode conflict handling (§13.4, §14.5).
 
 ### v1.4 (2025-11-05)
 
-- Removed JavaScript-specific normalization details; replaced with language-agnostic requirements (Section 3).
-- Defined canonical number format for encoders and decoder acceptance rules (Section 2).
-- Added Appendix G with host-type normalization examples for Go, JavaScript, Python, and Rust.
-- Clarified non-strict mode tab handling as implementation-defined (Section 12).
-- Expanded regex notation for cross-language clarity (Section 7.3).
+- Generalized normalization and numeric canonicalization rules, and added host-type normalization guidance (Appendix G).
 
 ### v1.3 (2025-10-31)
 
-- Added numeric precision requirements: JavaScript implementations SHOULD use Number.toString() precision (15-17 digits), all implementations MUST preserve round-trip fidelity (Section 2).
-- Added RFC 5234 core rules (ALPHA, DIGIT, DQUOTE, HTAB, LF, SP) to ABNF grammar definitions (Section 6).
+- Added numeric precision guidance and ABNF core rules for headers and keys (§2, §6).
 
 ### v1.2 (2025-10-29)
 
-- Clarified delimiter scoping behavior between array headers.
-- Tightened strict-mode indentation requirements: leading spaces MUST be exact multiples of indentSize; tabs in indentation MUST error.
-- Defined blank-line and trailing-newline decoding behavior with explicit skipping rules outside arrays.
-- Clarified hyphen-based quoting: "-" or any string starting with "-" MUST be quoted.
-- Clarified BigInt normalization: values outside safe integer range are converted to quoted decimal strings.
-- Clarified row/key disambiguation: uses first unquoted delimiter vs colon position.
+- Tightened delimiter scoping, indentation, blank-line handling, hyphen-based quoting, BigInt normalization, and row/key disambiguation rules (§2, §9, §11-§12).
 
 ### v1.1 (2025-10-29)
 
-Added strict-mode rules, delimiter-aware parsing, and decoder options (indent, strict).
+- Introduced strict-mode validation, delimiter-aware parsing, and decoder options (indent, strict).
 
 ### v1.0 (2025-10-28)
 
-Initial encoding, normalization, and conformance rules.
+- Initial specification: encoding normalization, decoding interpretation, and conformance requirements.
 
 ## Appendix E: Acknowledgments and License
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@toon-format/spec",
   "type": "module",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "packageManager": "pnpm@10.19.0",
   "description": "Official specification for Token-Oriented Object Notation (TOON)",
   "author": "Johann Schopplich <hello@johannschopplich.com>",

package/tests/fixtures/decode/arrays-nested.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.4",
+  "version": "2.1",
   "category": "decode",
   "description": "Nested and mixed array decoding - list format, arrays of arrays, root arrays, mixed types",
   "tests": [
@@ -52,7 +52,7 @@
       "specSection": "9.4"
     },
     {
-      "name": "parses nested tabular arrays as first field on hyphen line",
+      "name": "parses nested tabular arrays as first field on hyphen line (legacy)",
       "input": "items[1]:\n  - users[2]{id,name}:\n    1,Ada\n    2,Bob\n    status: active",
       "expected": {
         "items": [
@@ -65,14 +65,33 @@
           }
         ]
       },
-      "specSection": "10"
+      "specSection": "10",
+      "note": "Still valid for backward compatibility"
+    },
+    {
+      "name": "parses nested tabular arrays in list items with bare hyphen",
+      "input": "items[1]:\n  -\n    users[2]{id,name}:\n      1,Ada\n      2,Bob\n    status: active",
+      "expected": {
+        "items": [
+          {
+            "users": [
+              { "id": 1, "name": "Ada" },
+              { "id": 2, "name": "Bob" }
+            ],
+            "status": "active"
+          }
+        ]
+      },
+      "specSection": "10",
+      "minSpecVersion": "2.1",
+      "note": "Canonical v2.1+ encoding (bare hyphen with all fields indented)"
     },
     {
       "name": "parses objects containing arrays (including empty arrays) in list format",
-      "input": "items[1]:\n  - name: test\n    data[0]:",
+      "input": "items[1]:\n  - name: Ada\n    data[0]:",
       "expected": {
         "items": [
-          { "name": "test", "data": [] }
+          { "name": "Ada", "data": [] }
         ]
       },
       "specSection": "9.4"
@@ -120,35 +139,41 @@
       "specSection": "9.2"
     },
     {
-      "name": "parses root arrays of primitives (inline)",
+      "name": "parses root-level primitive array inline",
       "input": "[5]: x,y,\"true\",true,10",
       "expected": ["x", "y", "true", true, 10],
       "specSection": "9.1"
     },
     {
-      "name": "parses root arrays of uniform objects in tabular format",
+      "name": "parses root-level array of uniform objects in tabular format",
       "input": "[2]{id}:\n  1\n  2",
       "expected": [{ "id": 1 }, { "id": 2 }],
       "specSection": "9.3"
     },
     {
-      "name": "parses root arrays of non-uniform objects in list format",
+      "name": "parses root-level array of non-uniform objects in list format",
       "input": "[2]:\n  - id: 1\n  - id: 2\n    name: Ada",
       "expected": [{ "id": 1 }, { "id": 2, "name": "Ada" }],
       "specSection": "9.4"
     },
     {
-      "name": "parses empty root arrays",
-      "input": "[0]:",
-      "expected": [],
-      "specSection": "9.1"
+      "name": "parses root-level array mixing primitive, object, and array of objects in list format",
+      "input": "[3]:\n  - summary\n  - id: 1\n    name: Ada\n  - [2]:\n    - id: 2\n    - status: draft",
+      "expected": ["summary", { "id": 1, "name": "Ada" }, [{ "id": 2 }, { "status": "draft" }]],
+      "specSection": "9.4"
     },
     {
-      "name": "parses root arrays of arrays",
+      "name": "parses root-level array of arrays",
       "input": "[2]:\n  - [2]: 1,2\n  - [0]:",
       "expected": [[1, 2], []],
       "specSection": "9.2"
     },
+    {
+      "name": "parses empty root-level array",
+      "input": "[0]:",
+      "expected": [],
+      "specSection": "9.1"
+    },
     {
       "name": "parses complex mixed object with arrays and nested objects",
       "input": "user:\n  id: 123\n  name: Ada\n  tags[2]: reading,gaming\n  active: true\n  prefs[0]:",
@@ -164,7 +189,7 @@
       "specSection": "8"
     },
     {
-      "name": "parses arrays mixing primitives, objects and strings (list format)",
+      "name": "parses arrays mixing primitives, objects, and strings in list format",
       "input": "items[3]:\n  - 1\n  - a: 1\n  - text",
       "expected": {
         "items": [1, { "a": 1 }, "text"]

package/tests/fixtures/decode/arrays-tabular.json

@@ -59,7 +59,7 @@
       "specSection": "9.3"
     },
     {
-      "name": "unquoted colon terminates tabular rows and starts key-value pair",
+      "name": "treats unquoted colon as terminator for tabular rows and start of key-value pair",
       "input": "items[2]{id,name}:\n  1,Alice\n  2,Bob\ncount: 2",
       "expected": {
         "items": [

package/tests/fixtures/decode/delimiters.json

@@ -66,7 +66,7 @@
       "specSection": "11"
     },
     {
-      "name": "nested arrays inside list items default to comma delimiter",
+      "name": "parses nested arrays inside list items with default comma delimiter",
       "input": "items[1\t]:\n  - tags[3]: a,b,c",
       "expected": {
         "items": [{ "tags": ["a", "b", "c"] }]
@@ -75,7 +75,7 @@
       "note": "Parent uses tab, nested defaults to comma"
     },
     {
-      "name": "nested arrays inside list items default to comma with pipe parent",
+      "name": "parses nested arrays inside list items with default comma delimiter when parent uses pipe",
       "input": "items[1|]:\n  - tags[3]: a,b,c",
       "expected": {
         "items": [{ "tags": ["a", "b", "c"] }]
@@ -83,25 +83,25 @@
       "specSection": "11"
     },
     {
-      "name": "parses root arrays with tab delimiter",
+      "name": "parses root-level array with tab delimiter",
       "input": "[3\t]: x\ty\tz",
       "expected": ["x", "y", "z"],
       "specSection": "11"
     },
     {
-      "name": "parses root arrays with pipe delimiter",
+      "name": "parses root-level array with pipe delimiter",
       "input": "[3|]: x|y|z",
       "expected": ["x", "y", "z"],
       "specSection": "11"
     },
     {
-      "name": "parses root arrays of objects with tab delimiter",
+      "name": "parses root-level array of objects with tab delimiter",
       "input": "[2\t]{id}:\n  1\n  2",
       "expected": [{ "id": 1 }, { "id": 2 }],
       "specSection": "11"
     },
     {
-      "name": "parses root arrays of objects with pipe delimiter",
+      "name": "parses root-level array of objects with pipe delimiter",
       "input": "[2|]{id}:\n  1\n  2",
       "expected": [{ "id": 1 }, { "id": 2 }],
       "specSection": "11"

package/tests/fixtures/decode/indentation-errors.json

@@ -4,7 +4,7 @@
   "description": "Strict mode indentation validation - non-multiple indentation, tab characters, custom indent sizes",
   "tests": [
     {
-      "name": "throws when object field has non-multiple indentation (3 spaces with indent=2)",
+      "name": "throws on object field with non-multiple indentation (3 spaces with indent=2)",
       "input": "a:\n   b: 1",
       "expected": null,
       "shouldError": true,
@@ -15,7 +15,7 @@
       "specSection": "14.3"
     },
     {
-      "name": "throws when list item has non-multiple indentation (3 spaces with indent=2)",
+      "name": "throws on list item with non-multiple indentation (3 spaces with indent=2)",
       "input": "items[2]:\n   - id: 1\n   - id: 2",
       "expected": null,
       "shouldError": true,
@@ -26,7 +26,7 @@
       "specSection": "14.3"
     },
     {
-      "name": "throws with custom indent size when non-multiple (3 spaces with indent=4)",
+      "name": "throws on non-multiple indentation with custom indent=4 (3 spaces)",
       "input": "a:\n   b: 1",
       "expected": null,
       "shouldError": true,
@@ -51,7 +51,7 @@
       "specSection": "12"
     },
     {
-      "name": "throws when tab character used in indentation",
+      "name": "throws on tab character used in indentation",
       "input": "a:\n\tb: 1",
       "expected": null,
       "shouldError": true,
@@ -61,7 +61,7 @@
       "specSection": "14.3"
     },
     {
-      "name": "throws when mixed tabs and spaces in indentation",
+      "name": "throws on mixed tabs and spaces in indentation",
       "input": "a:\n \tb: 1",
       "expected": null,
       "shouldError": true,
@@ -71,7 +71,7 @@
       "specSection": "14.3"
     },
     {
-      "name": "throws when tab at start of line",
+      "name": "throws on tab at start of line",
       "input": "\ta: 1",
       "expected": null,
       "shouldError": true,
@@ -144,7 +144,7 @@
       "specSection": "12"
     },
     {
-      "name": "empty lines do not trigger validation errors",
+      "name": "parses empty lines without validation errors",
       "input": "a: 1\n\nb: 2",
       "expected": {
         "a": 1,
@@ -156,7 +156,7 @@
       "specSection": "12"
     },
     {
-      "name": "root-level content (0 indentation) is always valid",
+      "name": "parses root-level content (0 indentation) as always valid",
       "input": "a: 1\nb: 2\nc: 3",
       "expected": {
         "a": 1,
@@ -169,7 +169,7 @@
       "specSection": "12"
     },
     {
-      "name": "lines with only spaces are not validated if empty",
+      "name": "parses lines with only spaces without validation if empty",
       "input": "a: 1\n   \nb: 2",
       "expected": {
         "a": 1,

package/tests/fixtures/decode/root-form.json

@@ -4,7 +4,7 @@
   "description": "Root form detection - empty document, single primitive, multiple primitives",
   "tests": [
     {
-      "name": "empty document decodes to empty object",
+      "name": "parses empty document as empty object",
       "input": "",
       "expected": {},
       "options": {

package/tests/fixtures/decode/validation-errors.json

@@ -18,14 +18,14 @@
       "specSection": "14.1"
     },
     {
-      "name": "throws when tabular row value count does not match header field count",
+      "name": "throws on tabular row value count mismatch with header field count",
       "input": "items[2]{id,name}:\n  1,Ada\n  2",
       "expected": null,
       "shouldError": true,
       "specSection": "14.1"
     },
     {
-      "name": "throws when tabular row count does not match header length",
+      "name": "throws on tabular row count mismatch with header length",
       "input": "[1]{id}:\n  1\n  2",
       "expected": null,
       "shouldError": true,

package/tests/fixtures/decode/whitespace.json

@@ -49,7 +49,7 @@
       "specSection": "12"
     },
     {
-      "name": "empty tokens decode to empty string",
+      "name": "parses empty tokens as empty string",
       "input": "items[3]: a,,c",
       "expected": {
         "items": ["a", "", "c"]

package/tests/fixtures/encode/arrays-nested.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.4",
+  "version": "2.1",
   "category": "encode",
   "description": "Nested and mixed array encoding - arrays of arrays, mixed type arrays, root arrays",
   "tests": [
@@ -50,14 +50,16 @@
     {
       "name": "encodes root-level array of non-uniform objects in list format",
       "input": [{ "id": 1 }, { "id": 2, "name": "Ada" }],
-      "expected": "[2]:\n  - id: 1\n  - id: 2\n    name: Ada",
-      "specSection": "9.4"
+      "expected": "[2]:\n  -\n    id: 1\n  -\n    id: 2\n    name: Ada",
+      "specSection": "9.4",
+      "minSpecVersion": "2.1"
     },
     {
-      "name": "encodes empty root-level array",
-      "input": [],
-      "expected": "[0]:",
-      "specSection": "9.1"
+      "name": "encodes root-level array mixing primitive, object, and array of objects in list format",
+      "input": ["summary", { "id": 1, "name": "Ada" }, [{ "id": 2 }, { "status": "draft" }]],
+      "expected": "[3]:\n  - summary\n  -\n    id: 1\n    name: Ada\n  - [2]:\n    -\n      id: 2\n    -\n      status: draft",
+      "specSection": "9.4",
+      "minSpecVersion": "2.1"
     },
     {
       "name": "encodes root-level arrays of arrays",
@@ -65,6 +67,12 @@
       "expected": "[2]:\n  - [2]: 1,2\n  - [0]:",
       "specSection": "9.2"
     },
+    {
+      "name": "encodes empty root-level array",
+      "input": [],
+      "expected": "[0]:",
+      "specSection": "9.1"
+    },
     {
       "name": "encodes complex nested structure",
       "input": {
@@ -84,16 +92,18 @@
       "input": {
         "items": [1, { "a": 1 }, "text"]
       },
-      "expected": "items[3]:\n  - 1\n  - a: 1\n  - text",
-      "specSection": "9.4"
+      "expected": "items[3]:\n  - 1\n  -\n    a: 1\n  - text",
+      "specSection": "9.4",
+      "minSpecVersion": "2.1"
     },
     {
       "name": "uses list format for arrays mixing objects and arrays",
       "input": {
         "items": [{ "a": 1 }, [1, 2]]
       },
-      "expected": "items[2]:\n  - a: 1\n  - [2]: 1,2",
-      "specSection": "9.4"
+      "expected": "items[2]:\n  -\n    a: 1\n  - [2]: 1,2",
+      "specSection": "9.4",
+      "minSpecVersion": "2.1"
     }
   ]
 }

package/tests/fixtures/encode/arrays-objects.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.4",
+  "version": "2.1",
   "category": "encode",
   "description": "Arrays of objects encoding - list format for non-uniform objects and complex structures",
   "tests": [
@@ -11,8 +11,9 @@
           { "id": 2, "name": "Second", "extra": true }
         ]
       },
-      "expected": "items[2]:\n  - id: 1\n    name: First\n  - id: 2\n    name: Second\n    extra: true",
-      "specSection": "9.4"
+      "expected": "items[2]:\n  -\n    id: 1\n    name: First\n  -\n    id: 2\n    name: Second\n    extra: true",
+      "specSection": "9.4",
+      "minSpecVersion": "2.1"
     },
     {
       "name": "uses list format for objects with nested values",
@@ -21,24 +22,27 @@
           { "id": 1, "nested": { "x": 1 } }
         ]
       },
-      "expected": "items[1]:\n  - id: 1\n    nested:\n      x: 1",
-      "specSection": "9.4"
+      "expected": "items[1]:\n  -\n    id: 1\n    nested:\n      x: 1",
+      "specSection": "9.4",
+      "minSpecVersion": "2.1"
     },
     {
       "name": "preserves field order in list items - array first",
       "input": {
-        "items": [{ "nums": [1, 2, 3], "name": "test" }]
+        "items": [{ "nums": [1, 2, 3], "name": "Ada" }]
       },
-      "expected": "items[1]:\n  - nums[3]: 1,2,3\n    name: test",
-      "specSection": "10"
+      "expected": "items[1]:\n  -\n    nums[3]: 1,2,3\n    name: Ada",
+      "specSection": "10",
+      "minSpecVersion": "2.1"
     },
     {
       "name": "preserves field order in list items - primitive first",
       "input": {
-        "items": [{ "name": "test", "nums": [1, 2, 3] }]
+        "items": [{ "name": "Ada", "nums": [1, 2, 3] }]
       },
-      "expected": "items[1]:\n  - name: test\n    nums[3]: 1,2,3",
-      "specSection": "10"
+      "expected": "items[1]:\n  -\n    name: Ada\n    nums[3]: 1,2,3",
+      "specSection": "10",
+      "minSpecVersion": "2.1"
     },
     {
       "name": "uses list format for objects containing arrays of arrays",
@@ -47,8 +51,9 @@
           { "matrix": [[1, 2], [3, 4]], "name": "grid" }
         ]
       },
-      "expected": "items[1]:\n  - matrix[2]:\n    - [2]: 1,2\n    - [2]: 3,4\n    name: grid",
-      "specSection": "10"
+      "expected": "items[1]:\n  -\n    matrix[2]:\n      - [2]: 1,2\n      - [2]: 3,4\n    name: grid",
+      "specSection": "10",
+      "minSpecVersion": "2.1"
     },
     {
       "name": "uses tabular format for nested uniform object arrays",
@@ -57,8 +62,10 @@
           { "users": [{ "id": 1, "name": "Ada" }, { "id": 2, "name": "Bob" }], "status": "active" }
         ]
       },
-      "expected": "items[1]:\n  - users[2]{id,name}:\n    1,Ada\n    2,Bob\n    status: active",
-      "specSection": "10"
+      "expected": "items[1]:\n  -\n    users[2]{id,name}:\n      1,Ada\n      2,Bob\n    status: active",
+      "specSection": "10",
+      "minSpecVersion": "2.1",
+      "note": "Bare hyphen format for multi-field objects with tabular arrays"
     },
     {
       "name": "uses list format for nested object arrays with mismatched keys",
@@ -67,50 +74,67 @@
           { "users": [{ "id": 1, "name": "Ada" }, { "id": 2 }], "status": "active" }
         ]
       },
-      "expected": "items[1]:\n  - users[2]:\n    - id: 1\n      name: Ada\n    - id: 2\n    status: active",
-      "specSection": "10"
+      "expected": "items[1]:\n  -\n    users[2]:\n      -\n        id: 1\n        name: Ada\n      -\n        id: 2\n    status: active",
+      "specSection": "10",
+      "minSpecVersion": "2.1"
     },
     {
       "name": "uses list format for objects with multiple array fields",
       "input": {
         "items": [{ "nums": [1, 2], "tags": ["a", "b"], "name": "test" }]
       },
-      "expected": "items[1]:\n  - nums[2]: 1,2\n    tags[2]: a,b\n    name: test",
-      "specSection": "10"
+      "expected": "items[1]:\n  -\n    nums[2]: 1,2\n    tags[2]: a,b\n    name: test",
+      "specSection": "10",
+      "minSpecVersion": "2.1"
     },
     {
       "name": "uses list format for objects with only array fields",
       "input": {
         "items": [{ "nums": [1, 2, 3], "tags": ["a", "b"] }]
       },
-      "expected": "items[1]:\n  - nums[3]: 1,2,3\n    tags[2]: a,b",
-      "specSection": "10"
+      "expected": "items[1]:\n  -\n    nums[3]: 1,2,3\n    tags[2]: a,b",
+      "specSection": "10",
+      "minSpecVersion": "2.1"
     },
     {
       "name": "encodes objects with empty arrays in list format",
       "input": {
         "items": [
-          { "name": "test", "data": [] }
+          { "name": "Ada", "data": [] }
         ]
       },
-      "expected": "items[1]:\n  - name: test\n    data[0]:",
-      "specSection": "10"
+      "expected": "items[1]:\n  -\n    name: Ada\n    data[0]:",
+      "specSection": "10",
+      "minSpecVersion": "2.1"
     },
     {
-      "name": "places first field of nested tabular arrays on hyphen line",
+      "name": "uses bare hyphen for multi-field list-item objects with tabular arrays",
       "input": {
         "items": [{ "users": [{ "id": 1 }, { "id": 2 }], "note": "x" }]
       },
-      "expected": "items[1]:\n  - users[2]{id}:\n    1\n    2\n    note: x",
-      "specSection": "10"
+      "expected": "items[1]:\n  -\n    users[2]{id}:\n      1\n      2\n    note: x",
+      "specSection": "10",
+      "minSpecVersion": "2.1",
+      "note": "Multi-field objects use bare hyphen with all fields indented"
+    },
+    {
+      "name": "uses compact form for single-field list-item tabular arrays",
+      "input": {
+        "items": [{ "users": [{ "id": 1, "name": "Ada" }, { "id": 2, "name": "Bob" }] }]
+      },
+      "expected": "items[1]:\n  - users[2]{id,name}:\n    1,Ada\n    2,Bob",
+      "specSection": "10",
+      "minSpecVersion": "2.1",
+      "note": "Single-field objects with tabular arrays use compact form on hyphen line"
     },
     {
       "name": "places empty arrays on hyphen line when first",
       "input": {
         "items": [{ "data": [], "name": "x" }]
       },
-      "expected": "items[1]:\n  - data[0]:\n    name: x",
-      "specSection": "10"
+      "expected": "items[1]:\n  -\n    data[0]:\n    name: x",
+      "specSection": "10",
+      "minSpecVersion": "2.1"
     },
     {
       "name": "uses field order from first object for tabular headers",
@@ -124,15 +148,16 @@
       "specSection": "9.3"
     },
     {
-      "name": "uses list format when one object has nested column",
+      "name": "uses list format when one object has nested field",
       "input": {
         "items": [
           { "id": 1, "data": "string" },
           { "id": 2, "data": { "nested": true } }
         ]
       },
-      "expected": "items[2]:\n  - id: 1\n    data: string\n  - id: 2\n    data:\n      nested: true",
-      "specSection": "9.4"
+      "expected": "items[2]:\n  -\n    id: 1\n    data: string\n  -\n    id: 2\n    data:\n      nested: true",
+      "specSection": "9.4",
+      "minSpecVersion": "2.1"
     }
   ]
 }

package/tests/fixtures/encode/arrays-tabular.json

@@ -4,7 +4,7 @@
   "description": "Tabular array encoding - arrays of uniform objects with primitive values",
   "tests": [
     {
-      "name": "encodes arrays of similar objects in tabular format",
+      "name": "encodes arrays of uniform objects in tabular format",
       "input": {
         "items": [
           { "sku": "A1", "qty": 2, "price": 9.99 },

package/tests/fixtures/encode/delimiters.json

@@ -87,7 +87,7 @@
       "specSection": "11"
     },
     {
-      "name": "encodes root arrays with tab delimiter",
+      "name": "encodes root-level array with tab delimiter",
       "input": ["x", "y", "z"],
       "expected": "[3\t]: x\ty\tz",
       "options": {
@@ -96,7 +96,7 @@
       "specSection": "11"
     },
     {
-      "name": "encodes root arrays with pipe delimiter",
+      "name": "encodes root-level array with pipe delimiter",
       "input": ["x", "y", "z"],
       "expected": "[3|]: x|y|z",
       "options": {
@@ -105,7 +105,7 @@
       "specSection": "11"
     },
     {
-      "name": "encodes root arrays of objects with tab delimiter",
+      "name": "encodes root-level array of objects with tab delimiter",
       "input": [{ "id": 1 }, { "id": 2 }],
       "expected": "[2\t]{id}:\n  1\n  2",
       "options": {
@@ -114,7 +114,7 @@
       "specSection": "11"
     },
     {
-      "name": "encodes root arrays of objects with pipe delimiter",
+      "name": "encodes root-level array of objects with pipe delimiter",
       "input": [{ "id": 1 }, { "id": 2 }],
       "expected": "[2|]{id}:\n  1\n  2",
       "options": {