toon

README

toon

Encode-only Go implementation of TOON (Token-Oriented Object Notation), spec v3.3.

TOON is a line-oriented, indentation-based text format for the JSON data model. Compared with JSON it drops most punctuation, and arrays of uniform objects collapse to a single field header plus one delimited row per element — typically ~40% fewer LLM tokens than JSON for list-shaped data.

Install

go get github.com/moonrhythm/toon

Usage

b, err := toon.Marshal(v)

Marshal interprets v using encoding/json semantics — json struct tags (omitempty, -, renames) and custom MarshalJSON implementations are honored — then renders TOON. Anything that marshals correctly to JSON marshals correctly to TOON, with object key order and full number precision preserved.

type User struct {
	ID    int    `json:"id"`
	Name  string `json:"name"`
	Email string `json:"email"`
}

b, _ := toon.Marshal(map[string]any{
	"users": []User{
		{1, "Alice", "alice@example.com"},
		{2, "Bob", "bob@example.com"},
	},
})

users[2]{id,name,email}:
  1,Alice,alice@example.com
  2,Bob,bob@example.com

toon.MediaType (text/toon) is the format's provisional media type, for HTTP content negotiation.

Format choices

Output is deterministic with fixed spec-default options: 2-space indent, comma delimiter, length markers on, no key folding. There is no decoder — the format targets LLM consumers, which read it natively.

Conformance

The test suite includes the official encoder fixtures from the spec repository, and the encoder's output for every fixture plus an adversarial corpus round-trips cleanly through the reference TypeScript implementation's strict decoder.

License

MIT

Documentation

Overview

Package toon is an encode-only implementation of TOON (Token-Oriented Object Notation), spec v3.3 (https://github.com/toon-format/spec).

TOON is a line-oriented, indentation-based text format for the JSON data model. Compared with JSON it drops most punctuation (braces, brackets around every array element, quotes around most strings) and encodes arrays of uniform objects as a compact table with a single field header instead of repeating keys on every row. The result is a representation that costs far fewer tokens to feed to an LLM while remaining unambiguous and deterministic.

Only encoding is implemented; there is no decoder — the format targets LLM consumers, which read it natively.

Values are first interpreted using encoding/json semantics — json struct tags and custom json.Marshaler implementations are honored — then rendered as TOON. Anything that marshals correctly to JSON marshals correctly to TOON, with object key order and full number precision preserved.

Index

• Constants
• func Marshal(v any) ([]byte, error)

Constants

const MediaType = "text/toon"

MediaType is the provisional media type for TOON.

Functions

func Marshal

func Marshal(v any) ([]byte, error)

Marshal encodes v as TOON. v is first interpreted using encoding/json semantics — json struct tags and custom MarshalJSON implementations are honored — then rendered as TOON.