Toon

Toon

sigMAXToonprimitive cataloggenerationruntimeDSLWASMcontracts

TOON means Token-Oriented Object Notation.

It is a compact, human-readable notation for structured data. Its general goal is to encode JSON-like data with fewer tokens while keeping enough structure for humans and language models to inspect it reliably.

TOON is especially useful when data contains repeated records with the same fields. Instead of repeating every object key like JSON, it can declare the array length and fields once, then list rows in a compact table-like form.

Format concern	TOON approach
Nested objects	YAML-like indentation.
Uniform arrays	CSV-like rows with one shared field header.
Structure	Explicit array lengths and field lists.
Readability	Plain text, compact rows, minimal punctuation.
LLM prompts	Lower token overhead than verbose JSON for suitable data shapes.

General Shape

TOON keeps scalar values readable and uses table headers for arrays of uniform objects.

context:
  task: Runtime primitive catalog
  target: wasm32

primitives[3]{id,c_name,kind}:
input.read_object,input_read_object,host
response.status,response_status,host
string.trim,sx_trim,pure

The row header primitives[3]{id,c_name,kind} says there are three rows and each row has the same fields. This is the central trick: structure is still explicit, but repeated keys are not repeated on every row.

When It Fits

TOON is a good fit for compact catalog-like material:

• primitive lists;
• tool schemas;
• route inventories;
• generated artifact manifests;
• benchmark rows;
• small structured datasets sent to an LLM.

It is less useful when the data is deeply nested, highly irregular, or already smaller as plain JSON or CSV.

Use JSON for systems, TOON for compact context

TOON is best treated as a presentation and prompt format around structured data. JSON can remain the programmatic interchange format, while TOON gives humans and models a shorter view of the same information.

Toon In sigMAX

sigMAX uses Toon as a compact catalog notation in the runtime repository.

The important file today is runtime/functions.toon. It describes the primitive catalog used by generation: categories, C helper names, WASM imports, capabilities, signatures, pseudo-code aliases, limits and generation rules.

Role in sigMAX

Toon is not the runtime and it is not the business DSL itself. It is the catalog notation that makes the DSL vocabulary inspectable and easy to feed into generation tools.

sigMAX Catalog Content

runtime/functions.toon combines scalar metadata, rule lists and compact typed tables.

Section	Purpose
schema_version	Identifies the catalog schema.
runtime	Records Rust runtime, WASM target and C subset assumptions.
global_rules	Lists safety rules the generator must preserve.
forbidden_tokens	Lists code tokens that generated handlers must not use.
categories[...]	Defines primitive families such as input, response, storage, HTTP and JSON.
primitives[...]	Maps primitive IDs to C names, imports, capabilities and signatures.
pseudo_functions[...]	Maps compact @... DSL keywords to concrete C helpers.
limits[...]	Records bounded runtime defaults.
capability_rules	Explains when host primitives are allowed or denied.
llm_generation_rules	Constrains generated C subset code.
patterns[...]	Provides reusable generation patterns.

Why sigMAX Uses Toon

The primitive catalog is dense. YAML would be readable but verbose for repeated rows, while raw CSV would lose hierarchy and rule sections. Toon keeps the catalog compact without turning it into executable code.

Need	Toon contribution
Compact rows	Table blocks keep many primitives readable.
Typed columns	Headers document each column once.
Mixed content	Rules, limits and tables can live in one file.
Generation input	The catalog is deterministic enough to feed prompts or code generation.
Reviewability	Humans can audit primitive names, imports and capabilities in one place.

sigMAX Example

categories[3]{id,kind,description}:
input,host,Read route parameters or typed request bodies
response,host,Set status and emit structured ObjectIR
string,pure,Bounded string helpers

pseudo_functions[3]{pseudo,c_name}:
@body,input_read_object
@stat,response_status
@blank,sx_is_blank

In sigMAX, this means @body is not an invented keyword. It has a catalog entry, a concrete C lowering target and a runtime boundary.

sigMAX Design Rule

Toon should describe generation vocabulary and constraints, not hide behavior.

If a generated handler uses a pseudo keyword, the Toon catalog should make it possible to answer:

• which C helper or host import it lowers to;
• whether it is pure or host-controlled;
• which capability is required;
• which signature and limits apply;
• whether the binary contract must list a WASM import.

That keeps generation compact while preserving the contract-first audit trail.

References

• TOON format documentation
• TOON format repository

https://sigmax.dev/docs/generation/toon/