Empty arrays (eg `matches[0]:`) are often misinterpreted by LLMs

[bradvogel]

Issue Type

Other specification error

Description

This isn’t a bug in the spec, more a data point about how LLMs interpret empty arrays in TOON. For possible consideration in future iterations of this spec.

When encoding empty arrays, TOON produces:

$ npm ls @toon-format/toon
project0.0.1 /Users/dev
└── @toon-format/toon@1.2.0 -> ./../../node_modules/.pnpm/@toon-format+toon@1.2.0/node_modules/@toon-format/toon
$ node
> const { encode } = require('@toon-format/toon');
> console.log(encode({ log: { matches: [] } }))
log:
  matches[0]:

When I ask LLMs "were there any matches?", most respond with something like "yes (though it looks undefined / empty)". They seem to treat matches[0] as an array with a empty element at index 0.

Since TOON is explicitly designed as an LLM-friendly text format, this might be useful to re-consider.

Specification Reference

Array header syntax

Current Behavior

see above

Expected Behavior

n/a - this isn't a bug

Example

Impact

Devs need to work around this, eg

• giving LLM instructions on how to interpret TOON syntax
• replacing empty arrays with more explicit language like:

> console.log(encode({ log: {matches: 'none'}}))
log:
  matches: none

Proposed Fix

No response

Additional Context

No response

Checklist

• I have searched for similar issues in the issue tracker
• I have checked the latest version of the specification
• This issue is about the specification itself (not implementation bugs)

[bradvogel]

FYI for anyone following, here's a simple workaround:

import { encode } from '@toon-format/toon'

const data = { matches: [] }

const output = encode(data, {
  replacer: (_key, value) =>
    Array.isArray(value) && value.length === 0 ? '[]' : value,
});
console.log(output);

output:

matches: []

[bradvogel]

Likewise, LLMs (even GPT5.1) are getting confused by the single element array syntax, eg:

Write JS code to access the item id:

items[1]{type,id}:
    paragraph,e1

Answer:

items[1].id // Wrong. Should be: items[0].id

[bradvogel]

As a workaround, I'm currently post-processing tabul arrays toon output to:

// zero items uses `: []`
items: []

// 1 item uses `[]`
items[]{type,id}
   paragraph,e1

// multiple items stays the same
items[2]{type,id}
   paragraph,e1
   div,e2

These variants pass evals 100% of the time (caveat: only GPT5.1 tested).