toon/docs/reference/syntax-cheatsheet.md

Syntax Cheatsheet

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

Objects

::: code-group

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

id: 1
name: Ada

:::

Nested Objects

::: code-group

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

user:
  id: 1
  name: Ada

:::

Primitive Arrays

::: code-group

{
  "tags": ["foo", "bar", "baz"]
}

tags[3]: foo,bar,baz

:::

Tabular Arrays

::: code-group

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

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

:::

Mixed / Non-Uniform Arrays

::: code-group

{
  "items": [1, { "a": 1 }, "x"]
}

items[3]:
  - 1
  - a: 1
  - x

:::

Arrays of Arrays

::: code-group

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

pairs[2]:
  - [2]: 1,2
  - [2]: 3,4

:::

Root Arrays

::: code-group

["x", "y", "z"]

[3]: x,y,z

:::

Empty Containers

::: code-group

{}

(empty output)

:::

::: code-group

{
  "items": []
}

items[0]:

:::

Quoting Special Cases

Strings That Look Like Literals

::: code-group

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

version: "123"
enabled: "true"

:::

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

Strings with Active Delimiter

::: code-group

{
  "note": "hello, world"
}

note: "hello, world"

:::

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

Strings with Leading/Trailing Spaces

::: code-group

{
  "message": " padded "
}

message: " padded "

:::

Empty String

::: code-group

{
  "name": ""
}

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:

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

Escape Sequences

Only five escape sequences are valid in quoted strings:

Character	Escape
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

::: code-group

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

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

:::

The delimiter symbol appears inside the brackets and braces.

Key Folding (Optional)

Standard nesting:

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

With key folding (keyFolding: 'safe'):

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

See Format Overview – Key Folding for details.

Type Conversions

Input	Output
Finite number	Canonical decimal (no exponent, no trailing zeros)
NaN, Infinity, -Infinity	null
BigInt (safe range)	Number
BigInt (out of range)	Quoted decimal string
Date	ISO string (quoted)
undefined, function, symbol	null