スキーマの安定性

takuhon.json スキーマは、Takuhon のあらゆる出力面が依存する契約です — プロフィール ページ・JSON API・JSON-LD・MCP エンドポイント・書き出した CV はすべてこれを読みます。 1.0.0 以降、この契約は 凍結 されています。今日バリデーションを通るドキュメントは これからも通り続け、各フィールドの意味は固定されます。

1.「凍結」が保証すること

Takuhon はスキーマに セマンティックバージョニング を採用し、各 ドキュメント内の schemaVersion が準拠バージョンを記録します:

変更	バージョン	例
フィールドの削除・型変更・任意→必須への昇格・受理範囲の縮小	メジャー	recommendations の削除、careers の必須化
任意フィールドの追加・制約の緩和・enum 値の追加・拡張口の開放	マイナー	任意の pronouns フィールド追加
文言・ドキュメント・非規範的な修正	パッチ	—

要するに 「今日有効なドキュメントを無効化しうる変更はすべてメジャーリリース」 です。 マイナー・パッチリリースは takuhon.json に手を加えずに追従できます。

2. 既定で閉じている(closed)

1.0.0 以降、スキーマ内のすべてのオブジェクトは 閉じて います(additionalProperties: false)。スキーマが定義していないキーは、黙って無視されるのではなく バリデーション エラー になります。

{
  "profile": {
    "tittle": "Engineer"   // ❌ "title" のタイポ — 破棄ではなく拒否される
  }
}

1.0.0 以前は未知のキーが黙って破棄され、タイポを隠してデータを失う恐れがありました。 スキーマを閉じることで、タイポは明確に失敗し、JSON-LD と MCP に届くすべてのバイトが スキーマで定義されます。開いたままなのはロケールキーの文字列マップ ({ "en": "...", "ja": "..." })だけで、これは設計上あらゆる BCP-47 言語タグを受け入れます。

3. その他の 1.0.0 不変条件

• 空白のみの localized テキストは不可。 localized 値には少なくとも 1 つの非空白文字が 必要で、空白だけの文字列は空に解決されるのではなく拒否されます。
• 配列内で id が一意。 各エントリの id は配列内で一意でなければなりません。参照 フィールド(relatedCareerId・relatedEducationId)がこれに依存します。
• 安定した並び順。 項目は order の昇順で並び、欠落・同値は元の配列順を保ちます。
• 必須フィールドは最小限。 必須は schemaVersion・profile・contact・settings・ meta のみ。links・careers・projects・skills をはじめとするコンテンツ配列は すべて任意で、無い場合は空として扱われます。職歴のないプロフィールが空配列を持つ必要は もうありません。

4. 拡張

1.0.0 では独自キーは許可されません。スキーマをフォークせずに独自データを付与する将来の 非破壊な手段として x- 接頭辞が予約されていますが、これがマイナーリリースで導入される までは、x- 付きのキーも他の未知キーと同様に拒否されます。

5. 0.x からの移行

未知のキーを含まない 0.x ドキュメントは、構造を変えずにそのまま有効な 1.0.0 ドキュメント です — 1.0.0 の凍結はルールを厳格化しただけで、フィールドの移動はありません。バージョンを スタンプして適合を確認するには:

takuhon migrate ./takuhon.json   # 1.0.0 へ前方マイグレーション(バージョンのスタンプ)
takuhon validate ./takuhon.json  # 凍結スキーマへの適合を確認

validate が未知のキーを報告した場合、ほぼ確実にタイポか、1.0.0 以前に削除された フィールドです — 修正するか削除してください。定義済みフィールドの一覧は スキーマリファレンス を参照してください。