Revision 38 is a retained revision. It stays published at this address so hash-pinned references keep resolving, but it is no longer the working draft — revision 39 is.
Read this document in revision 39 →Revision 39·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, void 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 Part 3: JSON Encoding
The JSON encoding of the TSON schema system: how schema-governed TSON values are carried in RFC 8259 JSON — the annotation member namespace, the annotation object, atom lexical forms, container syntax, the treatment of void, and the discrimination predicate over the derived disjointness fact.
- 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], [TSON-SCHEMA] or [TSON-JSON], 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 void 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 where one is published. 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 38 — Change Log
Adjudicated 2026-10-26. The five normative artifacts and four resolved fixtures are at `/2026/38/` identities, re-stamped after adjudication for the doc lines §6 lists, each pin verified over the shipped bytes, and Part 2 §13.2 carries them (§6). Part 1, Part 2, Part 3 and the Developer Guide are revised against them in the order §3 lists; Part 3 arrived partly consumed and is completed in a second pass (§7); an independent verification pass over the four documents, the register and the artifacts is recorded in §8, and the implementation's own, which folded eleven findings into the text, in §9.
- SPEC-FEEDBACK.md (25 entries, renumbered against Revision 37; all new — Revision 37 closed every entry open against Revision 36)
- Revised companion artifacts at /2026/38/ identities: meta-kernel.tn, meta.tn, core.tn, net.tn, policy.tn and four resolved fixtures (implementing #2, #5, #6, #8, #9, #10, #12, #14, #15, #17, #22, #23 and #24)
- tson-part3-json.md, edited directly as findings arose (carrying the Part 3 halves of #1, #4, #10, #17 and #22)
- One level: schemas without the meta ladderLanded in Revision 39; step 7 built differently, one sub-step partly done, one deferred·Against TSON 2026 Revision 38 (Working Draft)·view raw ↗
Removes revision 38's meta ladder (!!meta as a rung, meta layers, placement, the import-level rule) in favour of one namespace per schema, a computed resolution order with a single cycle rule, one header directive, value entries of ordinary types and one reference atom. Its eight-step order of work landed in revision 39, with the kernel-namespace step built differently and extern deferred.
- The reference: one syntax, one valueLanded in Revision 39, its data spelling changed·Against TSON 2026 Revision 38 (Working Draft)·view raw ↗
Step 6 of One Level: one grammar for a qualified name with its arguments, written wherever a type is named, and that grammar the value of a single kernel reference atom. kind_type, ref_type and the type_argument record go, leaving meta.ref<T> as the one spelling; in data the argument list is written unquoted rather than quoted as first proposed.
- The kernel under its own name: meta.integer_type
Step 7 of One Level: put the kernel's declarations under names of its own so that an importing schema reserves few names. As built, the kernel is one document holding six open concept maps (meta, atom, numeric, unicode, net, binary) beside thirteen root names an author writes, with every name resolved from the root and no re-exports.
- Typed facets: retiring "value" from meta.tn
Step 8 of One Level: declare each atom constructor beside its canonical instance and type its facets by that instance, so value and value_type leave the kernel. Adds a value-to-value edge to the resolution order: a value read against an atom waits on that atom's facets.
- Dependent fields: sibling!
A record field whose type is the type a sibling field names, spelled value?: type!, so that a field's default and pin have their real type in the kernel. Lands as a reference spelling governed by an allow_sibling facet on meta.reference_type, and takes away the last uses of meta.value.
- Implementation Feedback
The first implementation's register of issues, ambiguities and inconsistencies found in revision 38's Parts 1 and 2: 24 entries, each giving the section, the problem, the reading chosen and, where one runs, the as-built design. It is what revision 39 adjudicates, and the design notes beside it land through its entries #4 to #22.
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.