Revision 35Current working draft·All revisions
Specification
The TSON specification, split into two parts, plus the companion documents developed alongside it. Spot an error, or have a comment on the specification? Open an issue on GitHub.
TSON Specification
- TSON Part 1: Text Data Format
The notation and reference encoding of the TSON schema system: the lexer, structural grammar, absent sentinel, augmentation syntax (annotations, type annotations, directives), and base type resolution — everything needed to losslessly read and write schemaless TSON data.
- TSON Part 2: Type System and Schema
The centre of the TSON series: the schema grammar, the type system and its operations, the schema chain and its resolution model, schema compilation and resolver output, the text encoding rules, and the operations of the schema, meta, and import directives.
- TSON Developer Guide
Rationale, extended examples, and implementation guidance for the TSON specification series. Nothing in this guide is normative; where it appears to disagree with [TSON-DATA] or [TSON-SCHEMA], the specifications govern.
Skills
Agent skills that teach an AI assistant to read and write TSON against this revision. Each bundles this revision's own schema sources, so a skill and the spec it describes never drift apart. Unzip a bundle into ~/.claude/skills/for Claude Code, or upload it in claude.ai under Settings › Features.
- tson-data.skill
Write, read, convert, and fix TSON data documents (.tn files) — the Typed Schema Object Notation text format, JSON-like but not a JSON superset, with optional quotes and commas, records vs maps, the absent sentinel `_` (there is no `null`), annotations (`@`), type annotations (`!uuid`, `!date`, `!bytes`…) and directives (`!!id`, `!!schema`).
- tson-schema.skill
Author, review, and explain TSON schema documents — `.tn` files with a `!!meta` header and name-to-type declarations that define records, enums, refined atoms with facets like min and max, choices, generic templates with type parameters, field groups, and constraints for the TSON (Typed Schema Object Notation) type system at tson.io.
Schema Source Files
The normative TSON schema source files in .tnformat, each followed in parentheses by its non-normative resolved-output fixture. To check an implementation: parse the source, run the resolver, canonicalise, and compare against the fixture.
Reports
The working documents belonging to this revision: the change log of what was accepted into it, and the non-normative reports written against it, which record findings and design directions under consideration rather than committed specification.
- TSON 2026 Revision 35 — Change Log
Adjudicated 2026-09-04; second pass 2026-09-05 (§8). Part 1, Part 2, the developer guide and the six companion artifacts are updated; the hash chain is re-stamped and Part 2 §13.2 carries the final pins.
- SPEC-FEEDBACK.md (36 entries, against Revision 34)
- Revised companion artifacts at /2026/35/ identities: meta-kernel.tn, meta.tn, core.tn and resolved fixtures (implementing #4, #7, #23, #24, #25, #26, #28, #29, #31, #32, #36)
- SPEC-FEEDBACK.md, renumbered against Revision 35 (8 entries: #1–#4 carried, #5–#8 new), with the artifacts revised a second time (§8)
Implementations of TSON (parsers, encoders, libraries) may be licensed however you choose; the specification's license applies to the written text, not to code that implements it.