Tot: JSON with the punctuation removed

Tot v0.1.0 is out. It’s a configuration language with a Rust library, a tot CLI, and a playground at totlang.dev. Source and binaries are on GitHub.

It is JSON with the punctuation removed. Whitespace-delimited key value pairs, no commas, no colons, bare keys, quoted string values.

name "example-service"
version 3

listen {
  host "0.0.0.0"
  port 8080
}

regions ["us-west-2" "eu-central-1"]

, and : are skipped like whitespace, so every JSON file is already valid tot, byte for byte.

Why write another one

JSON is a wire format that got drafted into config duty, and it has no comments. YAML has comments and guesses at types: no becomes false, 2024-01-01 becomes a date, NO becomes Norway, and reindenting a block can change what it means. TOML is comfortable until documents nest.

Tot keeps JSON’s data model, splits its single number type into integers and floats, and adds comments. Nothing else: no dates, no anchors, no tags, no includes, no interpolation. Whitespace is only a delimiter, so a document can be written on one line and reformatting can never change its meaning.

One asymmetry does most of the work. Keys are bare, string values are quoted. A key is always a string, so a bareword there is unambiguous, and dots, dashes, and slashes are ordinary characters in one. A value’s type comes from its syntax, so kind curly is a parse error and kind "curly" is a string.

Bare string values were rejected because two adjacent barewords are undecidable. country united states has no recoverable meaning, and a b c d would silently become two members. The cost of the rule is a pair of quotes. The benefit is that no tot document can mean something other than what it looks like.

Where computation stops

Every config format eventually grows a way to build large documents out of small ones, and the formats that grew it badly are now programs you have to read as programs. So layering is a CLI operation rather than syntax. tot merge base.tot staging.tot regional/eu.tot folds documents left to right, and tot set writes one path.

What syntax there is lives in a separate file type. A .tott template is tot plus a (head arg) form wherever a value goes, and tot build turns one into a .tot document. The document is what gets committed, and every consumer reads that.

replicas (if (param "prod") 5 1)
regions  (import "regions.tot")

There are seven forms and no way to define an eighth. That constraint is the point: as soon as a template can define a function, people write libraries, and a config file becomes a program. Parens won the sigil because they never appear in data, so computation is distinguishable from data by looking, without knowing the form set. Reserving @ or $ instead would have cost @type and $ref, which are JSON-LD and JSON Schema, exactly the documents tot from json exists to read.

What’s in the box

• tot fmt, with --check for CI. The formatter preserves inline versus block and never reflows, so running it over minified JSON gives back one correctly-punctuated long line.
• tot check --strict, one opt-in lint: a member’s value must begin on its key’s line. Members have no separator, so a missing value shifts every member after it; this is what makes the error land in the right place every time. fmt fixes what the lint reports.
• Schemas that look like the data. A schema is a tot document with a type where each value would be, so it lines up with the config next to it. Every violation is reported, each with a caret and a tot get path.
• Conversion both ways for JSON, YAML, and TOML. JSON is lossless in both directions, since tot from json only reparses and reformats.
• A library with no dependencies, serde behind an off-by-default feature.

The docs at totlang.dev render the README and the spec directly, so they cannot fall behind the language, and the playground runs the real library compiled to WebAssembly. What it says about a document is what tot says about it.