Convert JSON to TOON

TOON Format Cheat Sheet

TOON
Dev Tools

If you have ever felt that JSON is too verbose (all those braces!) but YAML is a bit too "magical" and unpredictable, you might just fall in love with TOON. This format strikes a unique balance between human readability and machine parsing speed. It is designed to be dense, explicit, and incredibly fast to parse.

Whether you are migrating data or just trying to debug a configuration file, this cheat sheet covers the essential syntax you need to know.

The Philosophy: Less Noise, More Data

The first thing you will notice is that TOON looks a lot like YAML, but it behaves strictly like JSON. It ditches the opening and closing braces in favor of indentation and newlines, making your data look cleaner immediately.

Objects and Nesting

In JSON, you are used to wrapping everything in curly braces. In TOON, the structure is implied by indentation.

JSON:

TOON:

Notice that keys don’t require quotes unless they contain special characters, and the hierarchy is visually obvious.

The Power of Arrays

This is where TOON really diverges from other formats. TOON requires you to declare the length of the array in the key itself. This might seem odd at first, but it allows the parser to pre-allocate memory, making it blazingly fast.

Primitive Arrays

For simple lists of strings or numbers, TOON uses a compact, comma-separated syntax.

The Syntax: key[Length]: item1,item2,item3

If you have a root array (the whole file is just a list), it looks like this:

Tabular Arrays (The Killer Feature)

This is the feature that usually wins developers over. If you have an array of objects that all share the same keys (like rows in a database), TOON lets you define the schema once in the header and then just list the values. This removes massive amounts of redundancy found in JSON.

The Syntax: key[Rows]{col1,col2}:

JSON:

TOON:

This "CSV-inside-YAML" approach makes large datasets incredibly readable and compact.

Mixed and Nested Arrays

Sometimes data isn't uniform. If your array contains different types of data (numbers mixed with objects), or if it contains complex nested objects, TOON falls back to a bullet-point style syntax using hyphens.

You can even have arrays inside arrays. Note how the inner array also declares its length:

Quoting: When to Use It

One of the nicest things about TOON is that you rarely need quotes. You can write Hello 世界 👋 without wrapping it in "". However, because TOON tries to infer types (numbers, booleans), there are specific rules for when you must use quotes.

The "Must-Quote" List

You must wrap your string in double quotes "" if:

  1. It looks like a number or boolean: If you want the string "123" or "true", quote it. Otherwise, they become the number 123 and the boolean true.
  1. It contains delimiters: If your string has a comma , (or whatever your active delimiter is), quote it.
  1. It has whitespace edges: Leading or trailing spaces require quotes.
  1. It contains special characters: Characters like :, ", \, [, ], {, }.
  1. It is empty: An empty string is represented as "".

Examples:

Escape Sequences

Keep it simple. TOON only recognizes five escape sequences inside strings. Anything else is invalid.

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

Advanced Headers & Delimiters

What if your data is full of commas? You don't want to quote every single field. TOON allows you to change the delimiter in the array header.

You can use a Tab or a Pipe (|) by placing it inside the brackets or braces.

Pipe Delimiter Example:

By adding | in the header, the parser knows to look for pipes instead of commas, keeping your syntax clean.

Key Folding

If you have deep nesting but only one path of data, you don't need to indent five times. You can use dot notation (Key Folding) to flatten your structure.

Standard Nesting:

Folded (Cleaner):

Quick Type Reference

TOON maps directly to JSON types, but it handles JavaScript-specific edge cases gracefully to ensure valid output.

  • Numbers: Stored as canonical decimals. 1.0 becomes 1.
  • Infinity / NaN: These become null (since JSON doesn't support them).
  • Dates: Converted to quoted ISO strings.
  • Undefined/Functions: Converted to null.
  • Empty Objects: Represented as nothing (empty output).
  • Empty Arrays: Represented as key[0]:.

TOON is a format that rewards precision. It might take a moment to get used to counting your array items, but the payoff in readability and file size is well worth the effort. Happy coding!