Syntax Cheatsheet

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

Objects

::: code-group

json

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

yaml

id: 1
name: Ada

:::

Nested Objects

::: code-group

json

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

yaml

user:
  id: 1
  name: Ada

:::

Primitive Arrays

::: code-group

json

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

yaml

tags[3]: foo,bar,baz

:::

Tabular Arrays

::: code-group

json

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

yaml

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

:::

Mixed and Non-Uniform Arrays

::: code-group

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.

::: code-group

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

::: code-group

json

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

yaml

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

:::

Root Arrays

::: code-group

json

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

yaml

[3]: x,y,z

:::

Empty Containers

::: code-group

json

{}

yaml

(empty output)

:::

::: code-group

json

{
  "items": []
}

yaml

items: []

:::

Quoting Special Cases

Strings That Look Like Literals

::: code-group

json

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

yaml

version: "123"
enabled: "true"

:::

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

Strings Containing Delimiters

::: code-group

json

{
  "note": "hello, world"
}

yaml

note: "hello, world"

:::

Strings must be quoted when they contain the active delimiter (inside an array scope) or the document delimiter (object field values, comma by default).

Strings with Leading/Trailing Spaces

::: code-group

json

{
  "message": " padded "
}

yaml

message: " padded "

:::

Empty String

::: code-group

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: :, ", \, [, ], {, }, or any control character (U+0000–U+001F, including newline/tab/CR)
Contain the relevant delimiter – the active delimiter inside an array scope, or the document delimiter (comma by default) for object field values
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

Six escape sequences are valid in quoted strings:

Character	Escape
Backslash (`\`)	`\\`
Double quote (`"`)	`\"`
Newline	`\n`
Carriage return	`\r`
Tab	`\t`
Any other U+0000–U+001F control character	`\uXXXX`

Other escapes (e.g., \x, \0, \b) are invalid, and lone-surrogate \uXXXX values (U+D800–U+DFFF) are rejected.

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

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

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)
`Set`	Array of normalized values
`Map`	Object with `String(key)` keys
`undefined`, `function`, `symbol`	`null`

::: info TOON itself doesn't specify how Date should be encoded – the spec leaves this to implementations. This library emits an ISO 8601 string in quotes; other implementations may choose differently. :::