How TOON Encodes Nested Data

TOON is table-first, but it is a complete encoding of JSON: any JSON value round-trips. The encoder picks the most compact form that is still unambiguous. Here is what it does with nesting, using real encoder output.

Nested objects: indentation

An object inside an object is a key with a colon and nothing after it, followed by the members indented two spaces.

dataset:
  slug: tcp-ip-protocol-suite
  title: TCP/IP Protocol Suite

Arrays inside records

If every field of every record is a primitive, the array is a table. If a record has an array or a differently shaped object as a field, the table form no longer fits, and the encoder uses list form: one - item per record, with the first field on the hyphen line.

users[2]:
  - id: 1
    tags[2]: admin,dev
  - id: 2
    tags[1]: ops

Uniform nested objects fold into the header

When every record has a nested object with the same keys, the encoder declares the nested fields in the header and keeps the rows flat:

points[2]{id,pos{x,y}}:
  1,10,20
  2,15,25

That is the same data as [{"id":1,"pos":{"x":10,"y":20}},{"id":2,"pos":{"x":15,"y":25}}] with the keys written once.

Deep or irregular trees

Deeply nested, irregular structures have no repeated keys to remove, so TOON saves little there: it is a good fit for lookup tables and a modest one for configuration trees. Measure before you switch; the token measurement shows where it helps and where it does not.

Check your own data

Paste a nested JSON document into TOON Studio to see which form the encoder chooses and what it costs in bytes.