Revision 32 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 35 is.
Read this document in revision 35 →Revision 35·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
Design history, 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.
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 Change Report: Removal of Cross-Namespace Template Linkage
Removes the one place in the grammar where an unmarked token in a type-ref position resolves against the structure namespace, which was also a shadowing hazard. The kernel container constructors become parameterless, the map type gains a sugar form mirroring the data notation, and generic application becomes purely schema-local. Accepted in full into revision 33.
- Schema Language Mappings: Synthesis
Consolidates the five mapping reports into cross-cutting findings, a prioritised worklist for Part 2, and a shared converter architecture. Its headline result is that every construct in all five languages landed on existing machinery, a planned addition, or a principled decline — leaving the meta-kernel untouched.
- JSON Schema and OpenAPI → TSON
Maps JSON Schema 2020-12 and OpenAPI one-directionally and strictness-first, so that format annotations become validated core types while the constraint-algebra keywords (not, if/then/else, unevaluated*) stay excluded by design. Introduces the discriminator token and the rest field that let records stay closed.
- Protocol Buffers → TSON
Maps the protobuf IDL with protojson documents as the validation target. All three protobuf presence disciplines land on existing TSON field states with matching injection semantics, and field numbers and wire-encoding variants are preserved as annotations rather than type semantics.
- ASN.1 (X.680–X.683) → TSON
Maps ASN.1’s abstract syntax — the most architecturally TSON-like language examined, having separated abstract syntax from transfer syntax since 1984. Subtype constraints become refinements almost term-for-term; extensibility markers are the systematic tension against TSON’s closure.
- Apache Avro → TSON
Maps Avro, the one source language designed around schema evolution as its primary use case, which forces the writer/reader resolution question every other report deferred. Avro’s union JSON encoding turns out to be TSON’s labelled sum materialised on the wire.
- GraphQL SDL → TSON
Maps GraphQL SDL, which is a capability schema rather than a data schema: a response’s shape comes from the query, not from the type alone. Covers the input universe, the output type graph, and the per-query derivation that would make response contract validation possible.
- Implementation Feedback
Issues, ambiguities, and inconsistencies found in the specification while building the first implementation, each recorded with the reading that implementation chose and a suggested resolution. The most direct feedback loop the draft currently has.
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.