HN 日本語サマリー

← 一覧へ戻る
プログラミング

TSON – イミュータブルでハッシュ固定スキーマを持つJSONスーパーセット

TSON – A JSON superset with immutable, hash-pinned schemas (tson.io)

34 pointsby andrewjneumann28 コメント

要約

TSONは、イミュータブルでハッシュ固定スキーマを持つJSONのスーパーセットです。スキーマ定義自体がデータであり、ハッシュによって検証チェーン全体が保証されます。データフォーマットはUnicodeファーストのJSONスーパーセットで、より記述しやすいように設計されています。

全文翻訳

スキーマとデータ for AI。

TSON(Typed Schema Object Notation)は、AIに構造化された出力を一度の修正で提供します。スキーマはJSON Schemaの3分の1のトークンコストで、より多くの制約を課します。各ドキュメントはそのスキーマを名指しし、各スキーマはそのメタスキーマを名指しします — 1つのハッシュがチェーンを検証します。

「私がこれまでに見たスキーマバリデーターの中で最高の診断機能です。10個の意図的に埋め込まれたエラーを、一度のパスで全て検出し、それぞれにポインター、制約、値を示してくれます。ajvが一度に1つのマッチしないスキーマしか教えてくれないのとは対照的です。LLMのリトライループにとって、これはワンショット修理に相当します。」

— Claude Fable 5(リファレンス実装について)

ここから試せます!

読み込み

ブラウザでコンパイル

TSONのデータとスキーマドキュメントは、単一のLexer、単一のツールチェーン、単一の検証パスを共有します。両方のペインは編集可能で、表示されているすべてがブラウザで実行されます。2つのヘッダー内のすべての参照はハッシュによって固定されています:スキーマはその自身のコンテンツ、メタスキーマ、タイプライブラリを名指しし、ドキュメントはそのスキーマを名指しします。スキーマを編集すると、それらのピンが一致しなくなります — ドキュメントのハッシュは、それが自身を名指しできる行の下にあるすべてをカバーします。これがコンシューマーがバイトを信頼する前に検証するものであり、re-pinボタンが復元するものです。

JSON Dataに切り替えると、同じ値がプレーンJSONから同じスキーマに対して読み込まれます。JSONエンコーディングの下です。JSONはアパラタスを運びません:ページがスキーマとルートタイプを提供し、APIコントラクトがそうするように、そしてnullはTSONの_です。JSONには@アノテーションのためのチャネルがないため、オブザーバトリーのアノテーションはそこにはありません。

現在のステータス

完全に機能するJavaリファレンス実装が利用可能で、TypeScriptポートも利用可能です — これがブラウザで上記のドキュメントを検証するものです。仕様は2026年改訂シリーズの下で公開されており、バージョン1として凍結されるまで変更の対象となります。設計に興味がある場合は、フィードバックが設計を形作る段階です。

実装

ターミナルで実行します。

リファレンス実装はtson-javaです。コマンドラインツールのinit-exampleコマンドは、例のスキーマとデータドキュメントのペアを作成します。validateコマンドを使用して、データがスキーマに対してどのように検証されるかを確認できます。データを破損させると(例:年齢を引用符で囲む、フィールドを削除する)、パスと理由とともにすべての問題が一度に報告されます。上記のバリデーターはtson-typescriptで、ブラウザで同じパイプラインを実行するポートです。

実装を入手する →

TSON Schema

堅牢な基盤の上に構築された簡潔なスキーマ

本来なら検証コード全体に散らばってしまうようなコントラクトを、宣言で記述します。基盤は、JSONを理解し、シンタックスやコードが書かれる前に、第一原理からスキーマとは何かを導き出す18記事の研究シリーズです。XML Schema, JSON Schema, Protobuf, ASN.1, YAMLと比較した組み込み型を参照 →

§5.2

レコードとフィールド

フィールドは3つの質問に答えます。名前の?はキーが省略可能であることを示し、タイプの?はその値が_(void)であることを示します。~はデフォルト値を提供し、=は値を固定します。キーは、名前がそうでない限り必須です。

schema
config => {
  host:     text
  port?:    integer ~ 8080
  retries?: integer = 3
  comment?: text
  timeout:  duration?
}
data (retries injected; timeout written, and deliberately void)
!config { host: "prod.db.internal"  port: 5555  timeout: _ }

§5.3

配列、タプル、セット

サイズ指定された同種配列、固定形状タプル、ユニークメンバーセット。3つのコントラクトはすべて、データでは単一のブラケット構文として読み込まれます。

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.3

型付けされたキーを持つマップ

レコードは固定の名前付きフィールドを持ちますが、マップは可変な関連付けを持ち、そのキーは宣言されたタイプです — すべてのキーが文字列にフラット化されるわけではありません。サイズはマップを制約し、?はvoid値を受け入れます。

schema
by_id    => {uuid => employee}
holidays => {date => text; 1..}
readings => {datetime => number?}
data (a key is a value; a value may be void)
!holidays { 2026-01-26 => "Australia Day" }
!readings { "2026-07-01T09:00:00Z" => _ }

§5.5

アトムと列挙

アトムの制約語彙を^で絞り込むか、コンストラクタで新しいアトムファミリーを作成します。範囲はminとmaxで狭められ、進行はmultiple_ofで、疎なセットはmembersで指定します。このリファインメントはソースのIS-A関係を持ちます。列挙はそれ自身のファミリーであり、!enumを持つ名前、または!text_enumを持つ任意のテキストです。

schema
port   => !integer ^ { min: 1  max: 65535 }
sku    => !text ^ { pattern: "[A-Z]-[0-9]{3}" }
status => !integer ^ { members: [200 404 500] }
rank   => !enum [L1 L2 L3]
level  => !text_enum ["lightly active" "very active"]
data
!port 8080
!sku "A-123"
!status 404
!rank L2
!level "lightly active"

§5.8

コンポジション

宣言された祖先を持つ新しいフィールド:ticketはauditのIS-A関係にあり、寄与するフィールドセットは互いに排他的でなければなりません。サイレントなオーバーライドも、ダイヤモンドの曖昧性もありません。

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.2

密封されたファミリー

抽象基底クラスはそれ自体インスタンスを持たず、各メンバーは=?と書かれたフィールドを固定します。これにより、データはその値によって配置されます — OpenAPIのディスプリミネーター、密封されたインターフェース — タグなしで。ピンはロード時に明確にチェックされ、finalはレコードを拡張に対して閉じます。

schema
pet   => abstract { kind: text =?  name: text }
dog   => pet & { kind: = "dog"  breed: text }
cat   => pet & { kind: = "cat"  indoor: boolean }
owner => { name: text  pets: [pet] }
data (each pet placed by its kind; no tags)
!owner {
  name: "Ada"
  pets: [
    { kind: dog  name: Rex  breed: kelpie }
    { kind: cat  name: Tom  indoor: true }
  ]
}

§5.7

リファインメント

継承されたフィールドを何も追加せずに絞り込みます:デフォルト値は移動できますが、ピンは移動できず、コントラクトのみが狭まります。フィールドの3つの回答のそれぞれは一方向に移動し、元に戻ることはありません。

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

減算

削除が許可されており、明確です:publicはaccountのサブタイプではなく、解決された出力はそれを正確に記録します。

schema
account => { user: text  email: text  password: text }
public  => account - { password }
data
!public { user: "ada"  email: "ada@example.com" }

§5.4

選択(Choice)

和集合型(Sum types)。構造的に互いに素なバリアントはデータにタグを必要としませんが、重複するバリアントはタグを必要とします。リゾルバーがどちらかを導き出し、その答えはすべてのエンコーディングで保持されます。

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

フィールドグループ

構造的に表現された代替案:|は1つ以上のフィールドのオプションを区切り、データはその選択したオプションを自身のラベルの下に書き込みます。)+は少なくとも1つを要求します。合成タグは発明されません。

schema
contact  => { name: text  ( email: email | phone: text )+ }
endpoint => { ( host: text  port: uint16 | socket: text ) }
data (email, phone or both; one whole option)
!contact { name: "Grace Hopper"  phone: "555-0142" }
!endpoint { host: "db.internal"  port: 5432 }

§5.10

テンプレート

タイプパラメータと値パラメータの両方に対する、空白のある定義。各パラメータは、それが立つ場所から導出されるか、<T: text>のように境界付けられるタイプを持ち、すべてのアプリケーションはそのタイプに対してチェックされます。完全にバインドされたアプリケーションを名指しする宣言は、その名前の下でそのタイプです。

schema
paged        => <T> { items: [T]  cursor?: text }
labelled     => <T: text> { label: T  note?: text }
retry_policy => <N> { attempts?: integer ~ N }
checkout     => retry_policy<5>
data
!checkout { attempts: 10 }

§7.8

検証されたままの拡張ポイント

データが自身のタイプを名指しする位置。declaredはこのスキーマ内に選択を保持します。extern_ofは、名指しされた外部スキーマの任意のタイプを許可し、データは自身の固定された!!schemaでそれをバインドします。ペイロードは、それが名指しするタイプに対して完全に検証されます — これは、検証されていないデータへのエスケープハッチではありません。

schema
event => {
  at:      datetime
  subject: declared
  payload: extern_of<"https://example.com/claim.tn">
}
data (each value names its type; the foreign one names its schema too)
!event {
  at:      "2026-07-01T09:00:00Z"
  subject: !sku "A-123"
  payload:
    !!schema:"https://example.com/claim.tn?sha256=ac3f2e1a…"
    !claim { reference: "CLM-5678" }
}

スキーマのバージョン管理

新しい必須フィールドを簡単に追加

バージョン2では、personレコードに新しい必須フィールドemailが追加されました。ミュータブルなスキーマシステムでは、新しい必須フィールドの追加は普遍的に禁止されています。Google、Microsoft、ZalandoのAPIガイドラインはすべてその慣行を禁止しています。Protobufでさえ、必須キーワードを開発者が回避しなければならない危険なものとしてマークしています。これらのルールが存在するのは、単一の定義がそれに対して書かれたすべてのドキュメントに役立つように強制されるためです。TSONは、スキーマがイミュータブルであるため、この負担を取り除きます。バージョンは単に新しいハッシュを持つ新しいドキュメントです。2つのコントラクトは完全な強度で共存し、personを構成するemployeeは同じ宣言で新しい要件を継承します。

必須は必須を意味する

レコードは、将来の保護のために任意にオプションのフィールドを残したり、永遠に墓石を運んだりすることなく、そのタイプに対して完全に閉じられたままです。

未知のフィールドはエラー

未知のフィールドを許容することは、インプレース進化の単なる回避策です。それがないと、単純なタイプミスが即座にエラーを引き起こすのではなく、サイレントにデータをドロップします。

バージョンによるルーティング

スキーマハッシュはヘッダーまたは最初の行にあり、即座に検証できます。単一のサーバーは複数のバージョンを同時にバインドするか、ゲートウェイがリクエストを異なるバックエンドにルーティングします。

マイグレーションは差分

両方のスキーマはデータであるため、ツールが正確な構造差分を計算します。マイグレーションは、数学的に正確な入力と出力コントラクトを持つ純粋な変換になります。

バージョン管理の全容 →

TSON Data

読む価値のある表記法

スキーマシステムは、より良いJSONを必要としたため、JSONライクな表記法(同じ中括弧、角括弧、引用符付き文字列)を得ました。句読点はオプションで、タイプはリアルです。これはUnicodeファーストです。

同じデータ、両方の側面。

SyntaxJSON requiresMeaningTSON adds

§2.4

引用符はオプション

識別子とスカラー値は引用符なしのトークンで、Unicode識別子プロパティで定義されているため、ASCIIだけでなくすべてのスクリプトで機能します。引用符が必要なものだけを引用してください:スペース、コロン、自由なテキスト。

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

§2.4

カンマは空白文字

任意の空白文字が項目を区切ります。カンマも機能するため、JSONの習慣を引き継ぐことができます。末尾のカンマも問題ありません — TSONには省略がないため、余分なカンマが混同されるものはありません。

[1, 2, 3, 4, 5]
[1 2 3 4 5]

§7.6

実際に書ける数値

任意精度、16進数と2進数、および桁区切り文字は、注釈なしで解決されます。無限大とNaNは近似ティアの値であり、明示的な!float64が必要です。有理数と複素数は、ベース解像度がそれらを文字列として扱うため、それら自身の注釈も必要とします。

(closest you can get)
"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

§7.2.3

複数行の文字列

共通のインデントが削除されたトリプルクォートブロックにより、複数行のテキストはソースでは読みやすく、値では正確になります。

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

§2.6

実際のキーを持つマップ

JSONオブジェクトは、すべてのキーを文字列に強制します。TSONは、レコード(固定の名前付きフィールド)とマップ(可変な関連付け)を区別し、マップキーは任意の値を保持できます。

(keys stringified)
{ "1": "one", "2026-03-13": "launch" }
{ 1 => one  2026-03-13 => launch }

§2.9

Voidはnullではない

JSONは3つのジョブを実行するために2つの状態(キーがない、またはnull)を提供します。TSONにはnullはまったくありません:voidセンチネル_は「この位置は存在し、値を持たない」ことを示し、キーがない状態とは区別されます。これは配列でも機能しますが、配列ではキーがない状態は使えません。

(is this unset, unknown, or removed?)
"phone": null
phone: _   scores: [1 _ 3 _ 5]

§3.1

値と共に移動するメタデータ

アノテーションは、順序付けられ、保持されたメタデータを任意の Сにアタッチします:もはやデータを装う_commentフィールドはありません。これもTSONがコメント構文を必要としない理由です:アノテーションは解析を生き残ります。

(the workaround)
"phone_comment": "deprecated, use mobile",
"phone": "555-0100"
phone: @deprecated:"use mobile" "555-0100"

§5.1

必要なときにタイプを指定

タイプアノテーションは、値にそれが何であるかをタグ付けします。組み込みの語彙 — 日付、時刻、UUID、バイト、ネットワーク、正確な10進数 — はスキーマなしで機能し、値は文字列ではなくネイティブタイプに解析されます。経過時間とカレンダー期間は別々のタイプです。なぜなら、1ヶ月は固定長ではなく、1秒は固定長だからです。

(strings that mean things)
"id": "550e8400-e29b-41d4-a716-446655440000",
"price": 19.99, "ttl": "PT30M"
id: !uuid 550e8400-e29b-41d4-a716-446655440000
price: !number 19.99   ttl: !duration PT30M
term: !period P1Y   avatar: !bytes "iVBORw0KGgo="

セキュリティ

あなたが書かなかったドキュメントを読むために構築

モデル出力、パートナーのアップロード、見知らぬ人からのリクエスト:サービスが読むほとんどのドキュメントは、信頼していない誰かから来ています。準拠するすべてのTSONプロセッサは、3つの設定可能なポリシーを備えています:名前のための識別子ポリシー、値のためのトークンポリシー、そして制限ポリシー。識別子ポリシーと制限ポリシーはデフォルトで強制されます。トークンポリシーは、値はデータであるため、無制限で開始され、レンダリングまたはマッチングするサービスのために存在します。デプロイメントは、自身のコードまたはpolicy.tn語彙で書かれたポリシー文書で、ドキュメントやそれ自身のスキーマではなく、これら3つすべてを設定します。これらはそれ自身を証明できないためです。残りは設計によって閉じられています:パターンは線形時間でマッチするI-Regexpであり、展開するアンカーやエンティティはなく、双方向のオーバーライドは名前の中に隠れることができません。

見分けのつきにくい名前は拒否される

ラテン語のadminとキリル文字のаdminは、フィールド名またはスキーマが識別子として型付けする値として並んで座ることはできません。また、混合スクリプトや古い文字は名前から排除されます。デプロイメントは、制限レベルを設定したり、名前セグメントごとに適用したり、コードで別のスクリプトを許可したりできます。環境変数で許可することはできません。

すべての制限は設定可能

ネスト深度64、16MiBドキュメント、合計値のキャップ、16の外部スキーマ。デフォルトはタイトなエンドに設定されているため、それらに適合するドキュメントはどのプロセッサにも適合し、デプロイメントは必要に応じていずれかを引き上げます。

拒否は評決ではない

制限に達すると、制限と閾値を示す拒否が得られます。スタックオーバーフローや、有効なドキュメントが無効であると主張することは決してありません。

ポリシーは事前に知られている

すべての拒否は、Unicodeデータバージョンと、それが判断された識別子、トークン、および制限ポリシーを運びます。プロセッサは、policy.tnが宣言する唯一の形状で、それらを事前に述べます。これにより、ジェネレータは適合するドキュメントを作成できます。

比較方法 →

次に来るもの

1つのスキーマ。複数のエンコーディング。

TSONスキーマとその基盤となるタイプシステムは、エンコーディングに依存しません。ASN.1と同じアーキテクチャで、スキーマが製品であり、フォーマットがそれをサービスします。TSONテキストデータフォーマットは最初のエンコーディングであり、JSONは2番目です。これらは同じスキーマに対して読み込まれ、検証されます。TOONのようなコンパクトフォーマットやバイナリのエンコーディングルールが次に続きます。それぞれが同じスキーマ検証済み値を提供します。