バージョンと非推奨

公開したファイルの URL は変わりません（変わらない URL）。このページは、その約束を守りながらモデルをどう変えていくかをまとめます。

サブジェクトに 1 つのバージョン

バージョンはサブジェクト単位で、@context、語彙、そのサブジェクトのすべての JSON Schema が同じ番号を持ちます（例 transportation の 1.0.0）。番号は Semantic Versioning の考え方で上げます。

変更	上げる番号	例
意味も検証も変わらない修正	パッチ（1.0.1）	スキーマの説明文の誤字
互換性のある追加	マイナー（1.1.0）	任意の属性やモデルを足す、値域に値を足す
互換性のない変更	メジャー（2.0.0）	属性の名前や型を変える、属性や値を消す、任意の属性を必須にする

値域に値を足すのはマイナーですが、すべての値を扱う利用者は新しい値を知る必要があるので、Pull Request とモデルの注記（notes.yaml）に書きます。属性の意味は変えません。変えたいときは新しい属性（新しい IRI）を作ります。

古いバージョンも残る

新しいバージョンを出しても、古いバージョンの v1.0.0.jsonld や v1.0.0.json は同じ URL で公開され続けます。v1.jsonld のようなエイリアスは、同じメジャーの最新版を指します。保存したデータには完全なバージョンの URL を、新しい版に追従したいクライアントにはエイリアスを使います。

属性の非推奨

置き換える属性は、スキーマで x-deprecated を付け、モデルのページに「非推奨」と表示します。非推奨の属性は少なくとも次のマイナーバージョンまで残し、削除は次のメジャーバージョンで行います。

モデルの段階

段階	意味
提案	Issue。まだカタログにはない
draft	カタログにあり、検証されるが、まだ変わる可能性がある
stable	別々の組織による 2 つの実装が ADOPTERS.yaml にある（CI とレビュアーが確認）
deprecated	使わないでほしいモデル。公開は続け、URL は変わらない。後継があれば catalog.yaml の supersededBy に書き、ページと catalog.json に表示される

新しいサブジェクト、メジャーバージョン、stable への昇格は小さなグループが決めます。詳しくは CONTRIBUTING.md。

いまはプレリリース

正式公開までは、各サブジェクトの現行バージョン（1.0.0）を、番号を上げずにその場で修正できます。修正した Pull Request では、CI が変わった公開済みファイルを一覧にします。正式公開で published-manifest.json の prerelease を false にすると、公開済みファイルは一切変えられなくなり、変更は上の表のとおり新しいバージョンになります。