TSON (Typed Schema Object Notation)

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.§5.2Records and field statesFields are required by default. ~ supplies a default, = pins a value, ? makes the field optional. Five states, every one explicit in the declaration.schemaconfig => { host: text port: integer ~ 8080 retries: integer = 3 comment: text? }data!config { host: "prod.db.internal" port: 5555 }§5.3Arrays, tuples, setsSized homogeneous arrays, fixed-shape tuples, unique-membered sets. Three contracts that all read as one bracket syntax in the data.schematags => [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.5Atoms and enumsRefine 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.schemaport => !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.8CompositionNew fields with declared ancestry: ticket IS-A audit, and contributed field sets must be disjoint. No silent overrides, no diamond ambiguity.schemaaudit => { 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.7RefinementTighten inherited fields without adding any: defaults can move, pins can't, contracts only narrow. One transition table governs every step.schemaservice => { host: text port: integer ~ 8080 } production => service ^ { port: = 443 }data (port fixed at 443; value doesn't need repeating)!production { host: "prod.internal" }§5.9SubtractionRemoval is allowed, and loud: public is not substitutable for account, and the resolved output records exactly that.schemaaccount => { user: text email: text password: text } public => account - { password }data!public { user: "ada" email: "ada@example.com" }§5.4ChoiceSum types. Structurally disjoint variants need no tag in data; overlapping ones require one. The resolver derives which, per encoding.schemashape => (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.11Field groupsExactly-one-of, stated structurally: the data carries one member under its own label, and no synthetic tag is invented.schemacontact => { name: text ( email: email | phone: text ) }data (only phone or email is allowed)!contact { name: "Grace Hopper" phone: "555-0142" }§5.10TemplatesDefinitions with blanks, over type parameters and value parameters both. A fully bound application becomes a real, named type in the resolved schema.schemapaged => <T> { items: [T] cursor: text? } retry_policy => <N> { attempts: integer ~ N } checkout => retry_policy<5>data!checkout { attempts: 10 }Schema VersioningAdding a new required field with easeVersion 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 requiredRecords remain completely closed under their type with no fields left arbitrarily optional for future-proofing and no tombstones carried forever.Unknown fields are errorsTolerating 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 versionThe 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 diffBecause 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 →TSON DataA notation worth readingThe 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.4Quotes are optionalIdentifiers 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", "имя": "Алиса"tsoncity: Melbourne имя: Алиса§2.4Commas are whitespaceAny whitespace separates items; commas still work, so JSON habits carry over. Trailing commas remain errors in both.json[1, 2, 3, 4, 5]tson[1 2 3 4 5]§7.6Numbers you can actually writeArbitrary 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"tsonmask: 0xFF budget: 1_000_000 ratio: !rational "22/7" atoms: 6.02e23 limit: !float64 .inf gap: !float64 .nan§7.2.3Strings with more than one lineTriple-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"tsonpoem: """ Roses are red Violets are blue """§2.6Maps with real keysJSON 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.9Absent is not nullJSON 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": nulltsonphone: _ scores: [1 _ 3 _ 5]§3.1Metadata that travels with the valueAnnotations 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"tsonphone: @deprecated:"use mobile" "555-0100"§5.1Types when you want themType 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.99tsonid: !uuid 550e8400-e29b-41d4-a716-446655440000 price: !number 19.99CompatibilityEvery 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 statusTSON 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 nextOne 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.