TSON (Typed Schema Object Notation)

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.

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.

Get the implementation →

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 understanding JSON and deriving what a schema is, from first principles, before any syntax or code was written.

config => {
  host:    text
  port:    integer ~ 8080
  retries: integer = 3
  comment: text?
}

!config { host: "prod.db.internal"  port: 5555 }

tags   => [text; 1..10]
point  => [number, number]
badges => set<text>

!tags [urgent reviewed]
!point [3.5 7.2]
!badges [alpha beta]

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 L2

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"
}

service    => { host: text  port: integer ~ 8080 }
production => service ^ { port: = 443 }

!production { host: "prod.internal" }

account => { user: text  email: text  password: text }
public  => account - { password }

!public { user: "ada"  email: "ada@example.com" }

shape  => (circle | rect)
circle => { radius: number }
rect   => { width: number  height: number }
shapes => [shape; 1..5]

!shapes [
  !circle { radius: 4 }
  !rect { width: 2  height: 3 }
]

contact => {
  name: text
  ( email: email | phone: text )
}

!contact { name: "Grace Hopper"  phone: "555-0142" }

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

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.

The full versioning story →

TSON Data

A notation worth reading

The schema system required a better JSON, so it got a Unicode-first superset of JSON.

"city": "Melbourne", "имя": "Алиса"

city: Melbourne  имя: Алиса

"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 .nan

"poem": "Roses are red\nViolets are blue"

poem: """
  Roses are red
  Violets are blue
  """

{ "1": "one", "2026-03-13": "launch" }

{ 1 => one  2026-03-13 => launch }

"phone": null

phone: _   scores: [1 _ 3 _ 5]

"phone_comment": "deprecated, use mobile",
"phone": "555-0100"

phone: @deprecated:"use mobile" "555-0100"

"id": "550e8400-e29b-41d4-a716-446655440000",
"price": 19.99

id: !uuid 550e8400-e29b-41d4-a716-446655440000
price: !number 19.99

Compatibility

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.

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.