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.
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.
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.
Fields are required by default. ~ supplies a default, = pins a value, ? makes the field optional. Five states, every one explicit in the declaration.
Sized homogeneous arrays, fixed-shape tuples, unique-membered sets. Three contracts that all read as one bracket syntax in the data.
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.
New fields with declared ancestry: ticket IS-A audit, and contributed field sets must be disjoint. No silent overrides, no diamond ambiguity.
Tighten inherited fields without adding any: defaults can move, pins can't, contracts only narrow. One transition table governs every step.
Removal is allowed, and loud: public is not substitutable for account, and the resolved output records exactly that.
Sum types. Structurally disjoint variants need no tag in data; overlapping ones require one. The resolver derives which, per encoding.
Exactly-one-of, stated structurally: the data carries one member under its own label, and no synthetic tag is invented.
Definitions with blanks, over type parameters and value parameters both. A fully bound application becomes a real, named type in the resolved schema.
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.
Records remain completely closed under their type with no fields left arbitrarily optional for future-proofing and no tombstones carried forever.
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.
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.
Because both schemas are data a tool computes the exact structural diff. Migrations become pure transformations with mathematically precise input and output contracts.
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
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.
Any whitespace separates items; commas still work, so JSON habits carry over. Trailing commas remain errors in both.
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.
Triple-quoted blocks with common indentation stripped, so multi-line text stays readable in source and exact in value.
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 gives two states (key missing, or null) to do three jobs. TSON's absent sentinel _ says "this position exists and holds no 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.
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.
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.
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 chain walked end to end, versioning, worked examples, and the reasoning behind the design.
Text Data Format, Type System and Schema, Meta Schemas and Core types.
The schema model, derived from the physical constraints of serialized data.
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.
Source: Hacker News — This article was automatically imported from the source. Read full article at original source →
