feat!: standardized encoding for list-item objects (spec v3)

docs/.vitepress/theme/index.ts

@@ -10,7 +10,7 @@ const config: Theme = {
   extends: DefaultTheme,
   enhanceApp({ app }) {
     app.config.globalProperties.$spec = {
-      version: '2.1',
+      version: '3.0',
     }
     app.component('CopyOrDownloadAsMarkdownButtons', CopyOrDownloadAsMarkdownButtons)
   },

docs/guide/format-overview.md

@@ -107,6 +107,40 @@ items[3]:
 
 Each element starts with `- ` at one indentation level deeper than the parent array header.
 
+### Objects as List Items
+
+When an array element is an object, it appears as a list item:
+
+```yaml
+items[2]:
+  - id: 1
+    name: First
+  - id: 2
+    name: Second
+    extra: true
+```
+
+When a tabular array is the first field of a list-item object, the tabular header appears on the hyphen line, with rows indented two levels deeper and other fields indented one level deeper:
+
+```yaml
+items[1]:
+  - users[2]{id,name}:
+      1,Ada
+      2,Bob
+    status: active
+```
+
+When the object has only a single tabular field, the same pattern applies:
+
+```yaml
+items[1]:
+  - users[2]{id,name}:
+      1,Ada
+      2,Bob
+```
+
+This is the canonical encoding for list-item objects whose first field is a tabular array.
+
 ### Arrays of Arrays
 
 When you have arrays containing primitive inner arrays:

docs/index.md

@@ -20,7 +20,7 @@ hero:
       text: CLI
       link: /cli/
     - theme: alt
-      text: Spec v2.1
+      text: Spec v3.0
       link: /reference/spec
 
 features:

docs/reference/spec.md

@@ -9,7 +9,7 @@ You don't need this page to *use* TOON. It's mainly for implementers and contrib
 
 ## Current Version
 
-**Spec v{{ $spec.version }}** (2025-11-23) is the current stable version.
+**Spec v{{ $spec.version }}** (2025-11-24) is the current stable version.
 
 The spec defines a provisional media type and file extension in §18.2:
 

docs/reference/syntax-cheatsheet.md

@@ -97,6 +97,28 @@ items[3]:
 
 :::
 
+> [!NOTE]
+> When a list-item object has a tabular array as its first field, the tabular header appears on the hyphen line. Rows are indented two levels deeper than the hyphen, and other fields are indented one level deeper. This is the canonical encoding for this pattern.
+
+::: code-group
+
+```yaml [Multi-field object]
+items[1]:
+  - users[2]{id,name}:
+      1,Ada
+      2,Bob
+    status: active
+```
+
+```yaml [Single-field object]
+items[1]:
+  - users[2]{id,name}:
+      1,Ada
+      2,Bob
+```
+
+:::
+
 ## Arrays of Arrays
 
 ::: code-group