Skip to content

Syntax Cheatsheet ​

Quick reference for mapping JSON to TOON format. For rigorous, normative syntax rules and edge cases, see the Specification.

Objects ​

json
{
  "id": 1,
  "name": "Ada"
}
yaml
id: 1
name: Ada

Nested Objects ​

json
{
  "user": {
    "id": 1,
    "name": "Ada"
  }
}
yaml
user:
  id: 1
  name: Ada

Primitive Arrays ​

json
{
  "tags": ["foo", "bar", "baz"]
}
yaml
tags[3]: foo,bar,baz

Tabular Arrays ​

json
{
  "items": [
    { "id": 1, "qty": 5 },
    { "id": 2, "qty": 3 }
  ]
}
yaml
items[2]{id,qty}:
  1,5
  2,3

Mixed / Non-Uniform Arrays ​

json
{
  "items": [1, { "a": 1 }, "x"]
}
yaml
items[3]:
  - 1
  - a: 1
  - x

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.

yaml
items[1]:
  - users[2]{id,name}:
      1,Ada
      2,Bob
    status: active
yaml
items[1]:
  - users[2]{id,name}:
      1,Ada
      2,Bob

Arrays of Arrays ​

json
{
  "pairs": [[1, 2], [3, 4]]
}
yaml
pairs[2]:
  - [2]: 1,2
  - [2]: 3,4

Root Arrays ​

json
["x", "y", "z"]
yaml
[3]: x,y,z

Empty Containers ​

json
{}
yaml
(empty output)
json
{
  "items": []
}
yaml
items[0]:

Quoting Special Cases ​

Strings That Look Like Literals ​

json
{
  "version": "123",
  "enabled": "true"
}
yaml
version: "123"
enabled: "true"

These strings must be quoted because they look like numbers/booleans.

Strings with Active Delimiter ​

json
{
  "note": "hello, world"
}
yaml
note: "hello, world"

Strings containing the active delimiter (comma by default) must be quoted.

Strings with Leading/Trailing Spaces ​

json
{
  "message": " padded "
}
yaml
message: " padded "

Empty String ​

json
{
  "name": ""
}
yaml
name: ""

Quoting Rules Summary ​

Strings must be quoted if they:

  • Are empty ("")
  • Have leading or trailing whitespace
  • Equal true, false, or null (case-sensitive)
  • Look like numbers (e.g., "42", "-3.14", "1e-6", "05")
  • Contain special characters: :, ", \, [, ], {, }, newline, tab, carriage return
  • Contain the active delimiter (comma by default, or tab/pipe if declared in header)
  • Equal "-" or start with "-" followed by any character

Otherwise, strings can be unquoted. Unicode and emoji are safe:

yaml
message: Hello 世界 👋
note: This has inner spaces

Escape Sequences ​

Only five escape sequences are valid in quoted strings:

CharacterEscape
Backslash (\)\\
Double quote (")\"
Newline\n
Carriage return\r
Tab\t

All other escapes (e.g., \x, \u) are invalid.

Array Headers ​

Basic Header ​

key[N]:
  • N = array length
  • Default delimiter: comma

Tabular Header ​

key[N]{field1,field2,field3}:
  • N = array length
  • {fields} = column names
  • Default delimiter: comma

Alternative Delimiters ​

yaml
items[2	]{id	name}:
  1	Alice
  2	Bob
yaml
items[2|]{id|name}:
  1|Alice
  2|Bob

The delimiter symbol appears inside the brackets and braces.

Key Folding (Optional) ​

Standard nesting:

yaml
data:
  metadata:
    items[2]: a,b

With key folding (keyFolding: 'safe'):

yaml
data.metadata.items[2]: a,b

See Format Overview – Key Folding for details.

Type Conversions ​

InputOutput
Finite numberCanonical decimal (no exponent, no trailing zeros)
NaN, Infinity, -Infinitynull
BigInt (safe range)Number
BigInt (out of range)Quoted decimal string
DateISO string (quoted)
undefined, function, symbolnull