spec 1.0 · 規範

バージョニング

仕様、スキーマ、それらを実装するツールの 3 つは、それぞれ独立してバージョン付けされます。

仕様#

仕様は SemVer のバージョンを持ちます（現在は 1.0.0）。互換性を壊す変更にはメジャーバージョンが必要です。すべての変更はリポジトリの変更履歴に記録されます。
コンテキストレイヤーは、対象とする仕様系列を leji.json の中で、自らを名乗る leji キーによって宣言します（たとえば "leji": "1.0"）。これは OpenAPI の慣習に倣ったものです。値は仕様の系列（major.minor）であって、仕様のパッチバージョンではありません。パッチのリリース（1.0.0 から 1.0.1）は、系列を動かさずに文言やツールを整えるものなので、マニフェストはどのパッチをまたいでも "1.0" のままです。ツールは、最新の系列ではなく、宣言された系列に照らしてコンテキストレイヤーを検証しなければなりません（MUST）。

プレビュー系列#

仕様系列はプレビューとして指定されても構いません（MAY）。プレビュー系列はその場で改訂できます。すなわち、一般提供（GA）で凍結されるまでは、新しいバージョンへ上げるのではなく、本来なら互換性を壊すような形で変わっても構いません（MAY）。「互換性を壊す変更にはメジャーバージョンが必要」という規則（項目 1）と、「互換性のない形の変更では $id の系列が変わる」という規則（項目 3）が適用されるのは GA での凍結以降であって、系列がプレビューの間ではありません。GA で系列は凍結され、両方の規則が有効になります。

一般提供の前に出る系列は、その最初のリリースでそのことを宣言しなければなりません（MUST）。

1.0 系列は、v1.3.0 のリファレンスツールのリリースをもって凍結されています。この系列では、スキーマの変更は追加に限られ、$id は v1.0 のままです。互換性のない変更は必ず新しい系列として公開され、既存系列をそのまま置き換えることはありません。

スキーマ#

各スキーマは、https://leji.org/schemas/v<major>.<minor>/<name>.schema.json という形の安定した $id を持ちます。$id の系列が変わるのは、そのスキーマの形が互換性のない形で変わったときだけです。
公開された系列の中では、スキーマの変更は追加でなければなりません（MUST。新しい任意のフィールド）。フィールドの削除や意味の変更には、新しい系列が必要です。
マニフェスト以外の機械可読な成果物は、それが書かれた対象のスキーマ系列を schemaVersion で宣言します。マニフェストは、自らを名乗る leji キーで対象の仕様系列を宣言します（項目 2）。

安定集合#

次の要素は、仕様系列の中で凍結されます。ツール（将来の商用実装を含む）は、別途並行するスキーマを用意せず、これらを対象に実装できます。

マニフェストの形と、その固定のファイル名 leji.json
カテゴリ識別子（domain、system、practice、governance、decisions）
適合レベルの識別子（core、indexed、governed、federated）
machine-readable-surface.md に従う識別子とパスの正規化の規則
インデックスエントリ、変更履歴のエントリ、エージェントプロファイル、決定記録の各形

実装するツール（非規範的）#

SDK と CLI はそれぞれ独自の SemVer でバージョン付けされ、対応する仕様系列を宣言します。このリポジトリのリファレンス SDK は、npm パッケージの @leji-org/leji（packages/sdk）、PyPI パッケージの leji（packages/sdk-py）、Go モジュールの leji（packages/sdk-go、単一の静的バイナリ）です。いずれも同一の振る舞いをし、ひとつの共有フィクスチャ一式でテストされています。