TSON – A JSON superset with immutable, hash-pinned schemas

# TSON (Typed Schema Object Notation) Source: [https://tson.io/](https://tson.io/) ## Data with animmutableschema\. **TSON \(Typed Schema Object Notation\)**is a schema system with immutable, hash\-pinned schemas whose definitions are themselves data\. A document names its schema, the schema names its meta\-schema;**one hash verifies the whole chain**\. The finishing touch, TSON's data format is a Unicode\-first superset of JSON you'll actually enjoy writing\. TSON Data and Schemas documents share the same lexer, same tooling, same verification\. Schemas are maps with a compact grammar that's easy to read and write\. In this Schema,`person`is a record with two fields;`employee`combines person with department and level; the`level`field is an enum with a default; and all the fields are required by default\. ## Try it Skip the reading\.Run it\. There is a working implementation:[tson\-java](https://github.com/litterat/ltr8-io-tson-java)\. The command\-line tool's init\-example command writes you an example schema and a data document pair\. You can use the validate command to see how the data gets validated against the schema\. Break the data \(e\.g\. quote the age, delete a field\) and it reports every problem at once, each with a path and a reason\. [Get the implementation →](https://github.com/litterat/ltr8-io-tson-java) TSON Schema ## A succinct schema built on a solid foundation Contracts you'd otherwise scatter through validation code, stated in declarations\. The foundation: an[eighteen\-article research series](https://tson.io/research/proto-schema/part-1-a-theoretical-model-for-data-schemas)understanding JSON and deriving what a schema is, from first principles, before any syntax or code was written\. [§5\.2](https://tson.io/2026/32/tson-part2-schema#52-field-states) ### Records and field states Fields are required by default\. ~ supplies a default, = pins a value, ? makes the field optional\. Five states, every one explicit in the declaration\. schema ``` config => { host: text port: integer ~ 8080 retries: integer = 3 comment: text? } ``` data ``` !config { host: "prod.db.internal" port: 5555 } ``` [§5\.3](https://tson.io/2026/32/tson-part2-schema#53-type-expressions) ### Arrays, tuples, sets Sized homogeneous arrays, fixed\-shape tuples, unique\-membered sets\. Three contracts that all read as one bracket syntax in the data\. schema ``` tags => [text; 1..10] point => [number, number] badges => set<text> ``` data \(array, tuple and set all encode as array\) ``` !tags [urgent reviewed] !point [3.5 7.2] !badges [alpha beta] ``` [§5\.5](https://tson.io/2026/32/tson-part2-schema#55-constructor-application-and-atom-refinement) ### Atoms and enums Refine an atom's constraint vocabulary with ^, or mint a fresh atom family with a constructor\. The refinement IS\-A its source; the enum is its own family\. schema ``` port => !integer ^ { min: 1 max: 65535 } sku => !text ^ { pattern: "[A-Z]-[0-9]{3}" } rank => !enum [L1 L2 L3] ``` data ``` !port 8080 !sku "A-123" !rank L2 ``` [§5\.8](https://tson.io/2026/32/tson-part2-schema#58-supertype-composition) ### Composition New fields with declared ancestry: ticket IS\-A audit, and contributed field sets must be disjoint\. No silent overrides, no diamond ambiguity\. schema ``` audit => { created: datetime updated: datetime? } ticket => audit & { id: uuid title: text } ``` data ``` !ticket { created: 2026-07-01T09:00:00Z id: 550e8400-e29b-41d4-a716-446655440000 title: "Server unreachable" } ``` [§5\.7](https://tson.io/2026/32/tson-part2-schema#57-refinement) ### Refinement Tighten inherited fields without adding any: defaults can move, pins can't, contracts only narrow\. One transition table governs every step\. schema ``` service => { host: text port: integer ~ 8080 } production => service ^ { port: = 443 } ``` data \(port fixed at 443; value doesn't need repeating\) ``` !production { host: "prod.internal" } ``` [§5\.9](https://tson.io/2026/32/tson-part2-schema#59-subtraction) ### Subtraction Removal is allowed, and loud: public is not substitutable for account, and the resolved output records exactly that\. schema ``` account => { user: text email: text password: text } public => account - { password } ``` data ``` !public { user: "ada" email: "[email protected]" } ``` [§5\.4](https://tson.io/2026/32/tson-part2-schema#54-choice-types) ### Choice Sum types\. Structurally disjoint variants need no tag in data; overlapping ones require one\. The resolver derives which, per encoding\. schema ``` shape => (circle | rect) circle => { radius: number } rect => { width: number height: number } shapes => [shape; 1..5] ``` data \(type tag required for records\) ``` !shapes [ !circle { radius: 4 } !rect { width: 2 height: 3 } ] ``` [§5\.11](https://tson.io/2026/32/tson-part2-schema#511-field-groups) ### Field groups Exactly\-one\-of, stated structurally: the data carries one member under its own label, and no synthetic tag is invented\. schema ``` contact => { name: text ( email: email | phone: text ) } ``` data \(only phone or email is allowed\) ``` !contact { name: "Grace Hopper" phone: "555-0142" } ``` [§5\.10](https://tson.io/2026/32/tson-part2-schema#510-templates-and-parameters) ### Templates Definitions with blanks, over type parameters and value parameters both\. A fully bound application becomes a real, named type in the resolved schema\. schema ``` paged => <T> { items: [T] cursor: text? } retry_policy => <N> { attempts: integer ~ N } checkout => retry_policy<5> ``` data ``` !checkout { attempts: 10 } ``` ## Schema Versioning Adding a newrequiredfield with ease Version 2 just added a new required email field to the person record\. In mutable schema systems, adding a new required field is universally forbidden\. The API guidelines for[Google](https://google.aip.dev/180),[Microsoft](https://github.com/microsoft/api-guidelines)and[Zalando](https://opensource.zalando.com/restful-api-guidelines/)all ban the practice\. Protobuf even marks the required keyword a hazard developers must avoid\. These rules exist because a single definition is forced to serve every document ever written against it\. TSON removes this burden because schemas are immutable\.**A version is simply a new document with a new hash**\. Two contracts coexist at full strength, and employee composing person inherits the new requirement in the same declaration\. ### Required means required Records remain completely closed under their type with no fields left arbitrarily optional for future\-proofing and no tombstones carried forever\. ### Unknown fields are errors Tolerating unknown fields is just a workaround for in\-place evolution\. Without it a simple typo triggers an immediate error instead of silently dropping data\. ### Route by version The schema hash sits in the header or on the first line for instant validation\. A single server binds multiple versions concurrently or a gateway routes requests to distinct backends\. ### Migration is a diff Because both schemas are data a tool computes the exact structural diff\. Migrations become pure transformations with mathematically precise input and output contracts\. [The full versioning story →](https://tson.io/2026/32/tson-guide) TSON Data ## A notation worth reading The schema system required a better JSON, so it got a Unicode\-first superset of JSON\. Same data, both sides\.syntax JSON requiresmeaning TSON adds [§2\.4](https://tson.io/2026/32/tson-part1-data#24-tokens) ### Quotes are optional Identifiers and scalar values are unquoted tokens, defined over Unicode identifier properties, so this works in every script, not just ASCII\. Quote only what needs quoting: spaces, colons, free text\. json ``` "city": "Melbourne", "имя": "Алиса" ``` tson ``` city: Melbourne имя: Алиса ``` [§2\.4](https://tson.io/2026/32/tson-part1-data#24-tokens) ### Commas are whitespace Any whitespace separates items; commas still work, so JSON habits carry over\. Trailing commas remain errors in both\. [§7\.6](https://tson.io/2026/32/tson-part1-data#76-number-grammar) ### Numbers you can actually write Arbitrary precision, hex and binary, and digit separators resolve with no annotation at all\. Infinities and NaN are approximate\-tier values and need an explicit \!float64; rationals and complex numbers need their own annotation too, since base resolution treats them as strings otherwise\. json \(closest you can get\) ``` "mask": 255, "budget": 1000000, "ratio": 3.142857142857143, "limit": "Infinity" ``` tson ``` mask: 0xFF budget: 1_000_000 ratio: !rational "22/7" atoms: 6.02e23 limit: !float64 .inf gap: !float64 .nan ``` [§7\.2\.3](https://tson.io/2026/32/tson-part1-data#723-multi-line-tokens) ### Strings with more than one line Triple\-quoted blocks with common indentation stripped, so multi\-line text stays readable in source and exact in value\. json ``` "poem": "Roses are red\nViolets are blue" ``` tson ``` poem: """ Roses are red Violets are blue """ ``` [§2\.6](https://tson.io/2026/32/tson-part1-data#26-map) ### Maps with real keys JSON objects force every key into a string\. TSON keeps records \(fixed named fields\) and maps \(variable associations\) distinct, and map keys can be any value\. json \(keys stringified\) ``` { "1": "one", "2026-03-13": "launch" } ``` tson ``` { 1 => one 2026-03-13 => launch } ``` [§2\.9](https://tson.io/2026/32/tson-part1-data#29-the-absent-sentinel) ### Absent is not null JSON gives two states \(key missing, or null\) to do three jobs\. TSON's absent sentinel \_ says "this position exists and holds no value"\. json \(is this unset, unknown, or removed?\) ``` "phone": null ``` tson ``` phone: _ scores: [1 _ 3 _ 5] ``` [§3\.1](https://tson.io/2026/32/tson-part1-data#31-annotations) ### Metadata that travels with the value Annotations attach ordered, preserved metadata to any value: no more "\_comment" fields pretending to be data\. This is also why TSON needs no comment syntax: annotations survive parsing\. json \(the workaround\) ``` "phone_comment": "deprecated, use mobile", "phone": "555-0100" ``` tson ``` phone: @deprecated:"use mobile" "555-0100" ``` [§5\.1](https://tson.io/2026/32/tson-part1-data#51-applicability) ### Types when you want them Type annotations tag a value with what it is\. A built\-in vocabulary \(dates, UUIDs, binary, precise numerics\) works with no schema at all, and the value parses to the native type, not a string\. json \(strings that mean things\) ``` "id": "550e8400-e29b-41d4-a716-446655440000", "price": 19.99 ``` tson ``` id: !uuid 550e8400-e29b-41d4-a716-446655440000 price: !number 19.99 ``` ## Compatibility Every valid JSON document is validTSON\. TSON is a strict superset of JSON, with its four atomic types \(null, boolean, number and string\), plusUUIDs,dates,binary data, andarbitrary\-precision numbersas first\-class values, parsed straight from quoted or unquoted text, no schema required\. ## Current status TSON is a**working draft**\. The specification is published under the 2026 revision series and remains subject to change until it freezes as version 1\. Implementations are underway: the first,[a Java implementation](https://github.com/litterat/ltr8-io-tson-java), is already functioning\. The meta\-kernel, meta\-schema, and core type library are already published with resolved fixtures, so parsers and resolvers will have reference answers to test against\. If the design interests you, this is the stage where feedback shapes it\. ## What comes next One schema\.Multiple encodings\. The TSON Schema and its underlying type system are agnostic to the encoding; the same architecture as ASN\.1, where the schema is the product and formats serve it\. The TSON text data format is the first encoding, but won't be the only one\. The plan is to develop encoding rules forJSON, compact formats likeTOON, andbinary, each carrying the same schema\-verified values\.