Data with an immutable schema.
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.
!!schema:"https://example.com/people.tn?sha256=c4d5e6f7…a2b3c4d5"
!employee {
name: "Ada Lovelace"
born: 1815-12-10
department: Research
level: L2
}
!!id:"https://example.com/people.tn?sha256=c4d5e6f7…a2b3c4d5"
!!meta:"https://tson.io/2026/32/m/meta.tn?sha256=8b1e4a9c…d7f2a640"
!!import:"https://tson.io/2026/32/m/core.tn?sha256=3f9d2c71…b8e5c194"
{
person => { name: text born: date }
employee => person & { department: text level: rank ~ L1 }
rank => !enum [L1 L2 L3]
}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. 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.
$ git clone https://github.com/litterat/ltr8-io-tson-java.git
$ cd ltr8-io-tson-java && ./gradlew :tson-cli:installDist
$ export PATH="$PWD/tson-cli/build/install/tson/bin:$PATH"
$ tson init-example
Wrote ./person.tn and ./person-data.tn.
$ tson validate person.tn person-data.tn
OKA 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 understanding JSON and deriving what a schema is, from first principles, before any syntax or code was written.
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.
config => {
host: text
port: integer ~ 8080
retries: integer = 3
comment: text?
}!config { host: "prod.db.internal" port: 5555 }Arrays, tuples, sets
Sized homogeneous arrays, fixed-shape tuples, unique-membered sets. Three contracts that all read as one bracket syntax in the data.
tags => [text; 1..10]
point => [number, number]
badges => set<text>!tags [urgent reviewed]
!point [3.5 7.2]
!badges [alpha beta]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.
port => !integer ^ { min: 1 max: 65535 }
sku => !text ^ { pattern: "[A-Z]-[0-9]{3}" }
rank => !enum [L1 L2 L3]!port 8080
!sku "A-123"
!rank L2Composition
New fields with declared ancestry: ticket IS-A audit, and contributed field sets must be disjoint. No silent overrides, no diamond ambiguity.
audit => { created: datetime updated: datetime? }
ticket => audit & { id: uuid title: text }!ticket {
created: 2026-07-01T09:00:00Z
id: 550e8400-e29b-41d4-a716-446655440000
title: "Server unreachable"
}Refinement
Tighten inherited fields without adding any: defaults can move, pins can't, contracts only narrow. One transition table governs every step.
service => { host: text port: integer ~ 8080 }
production => service ^ { port: = 443 }!production { host: "prod.internal" }Subtraction
Removal is allowed, and loud: public is not substitutable for account, and the resolved output records exactly that.
account => { user: text email: text password: text }
public => account - { password }!public { user: "ada" email: "ada@example.com" }Choice
Sum types. Structurally disjoint variants need no tag in data; overlapping ones require one. The resolver derives which, per encoding.
shape => (circle | rect)
circle => { radius: number }
rect => { width: number height: number }
shapes => [shape; 1..5]!shapes [
!circle { radius: 4 }
!rect { width: 2 height: 3 }
]Field groups
Exactly-one-of, stated structurally: the data carries one member under its own label, and no synthetic tag is invented.
contact => {
name: text
( email: email | phone: text )
}!contact { name: "Grace Hopper" phone: "555-0142" }Templates
Definitions with blanks, over type parameters and value parameters both. A fully bound application becomes a real, named type in the resolved schema.
paged => <T> { items: [T] cursor: text? }
retry_policy => <N> { attempts: integer ~ N }
checkout => retry_policy<5>!checkout { attempts: 10 }Schema Versioning
Adding a new required field with ease
!!id:"https://example.com/people-v2.tn?sha256=ac3f2e1a…a8e5be21"
!!meta:"https://tson.io/2026/32/m/meta.tn?sha256=8b1e4a9c…d7f2a640"
!!import:"https://tson.io/2026/32/m/core.tn?sha256=3f9d2c71…b8e5c194"
{
person => { name: text born: date email: text }
employee => person & { department: text level: rank ~ L1 }
rank => !enum [L1 L2 L3]
}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, Microsoft and Zalando 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.
A notation worth reading
The schema system required a better JSON, so it got a Unicode-first superset of JSON.
{
"name": "Ada Lovelace",
"born": "1815-12-10",
"fields": ["mathematics", "computing"],
"verified": true,
"note": null
}{
name: "Ada Lovelace"
born: !date 1815-12-10
fields: [mathematics computing]
verified: true
note: null
}Same data, both sides.syntax JSON requiresmeaning TSON adds
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.
"city": "Melbourne", "имя": "Алиса"city: Melbourne имя: АлисаCommas are whitespace
Any whitespace separates items; commas still work, so JSON habits carry over. Trailing commas remain errors in both.
[1, 2, 3, 4, 5][1 2 3 4 5]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.
"mask": 255, "budget": 1000000,
"ratio": 3.142857142857143, "limit": "Infinity"mask: 0xFF budget: 1_000_000 ratio: !rational "22/7"
atoms: 6.02e23 limit: !float64 .inf gap: !float64 .nanStrings with more than one line
Triple-quoted blocks with common indentation stripped, so multi-line text stays readable in source and exact in value.
"poem": "Roses are red\nViolets are blue"poem: """
Roses are red
Violets are blue
"""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.
{ "1": "one", "2026-03-13": "launch" }{ 1 => one 2026-03-13 => launch }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".
"phone": nullphone: _ scores: [1 _ 3 _ 5]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.
"phone_comment": "deprecated, use mobile",
"phone": "555-0100"phone: @deprecated:"use mobile" "555-0100"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.
"id": "550e8400-e29b-41d4-a716-446655440000",
"price": 19.99id: !uuid 550e8400-e29b-41d4-a716-446655440000
price: !number 19.99Compatibility
Every valid JSON document is valid TSON.
TSON is a strict superset of JSON, with its four atomic types (null, boolean, number and string), plus UUIDs, dates, binary data, and arbitrary-precision numbers as 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, 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.
The Developer Guide
The chain walked end to end, versioning, worked examples, and the reasoning behind the design.
Draft Specifications
Text Data Format, Type System and Schema, Meta Schemas and Core types.
The proto-schema research
The schema model, derived from the physical constraints of serialized data.
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 for JSON, compact formats like TOON, and binary, each carrying the same schema-verified values.