tson.io

Revision 37 is a retained revision, published . 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
    Draft 2026·Working Draft·view raw ↗

    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
    Draft 2026·Working Draft·view raw ↗

    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
    Draft 2026·Working Draft·view raw ↗

    The JSON encoding of the TSON schema system: how schema-governed TSON values are carried in RFC 8259 JSON — the reserved 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
    Draft 2026·Working Draft·view raw ↗

    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, the design proposals that landed in it, and the findings written against it. Reports are non-normative: they record reasoning and findings, not committed specification.

  • TSON 2026 Revision 37 — Change Log
    Against TSON 2026 Revision 36 (Working Draft)·view raw ↗

    Adjudicated 2026-10-07. Part 1, Part 2, Part 3 and the Developer Guide are updated; five companion artifacts are as received and `meta-kernel.tn` carries four doc edits made after its pin was stamped; the hash chain is re-stamped over the shipped bytes and Part 2 §13.2 carries the final pins (§6). Part 3 and the guide were completed in a second pass (§7).

    • SPEC-FEEDBACK.md (21 entries, renumbered against Revision 36: #1–#4 carried, #5–#21 new)
    • Revised companion artifacts at /2026/37/ identities: meta-kernel.tn, meta.tn, core.tn and resolved fixtures (implementing #7–#21)
    • tson-part3-json.md, edited directly as findings arose (carrying the Part 3 halves of #5, #7, #13, #14 and #18)
  • Specification Feedback
    Open register, input to Revision 38·view raw ↗

    The first implementation's register of issues, ambiguities and inconsistencies found in revision 37's Parts 1 and 2, as it stood when revision 38 closed it: 25 entries, from the network library and host types to record name types, kinds and namespaces, each giving the section, the problem, the reading chosen and, where one runs, the as-built design. Revision 38 closed every one.

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.