日本語
URL とバージョン
@context の URL はエンティティと一緒に保存され、何年も後に読まれます。このページでは、どの URL を使うか、カタログがその URL について何を約束するか、その約束を守りながらモデルをどう変えていくかを説明します。
プレリリース中
この約束は正式公開から適用されます。それまでは、公開済みのファイル(v1.0.0 を含む)も直接修正されることがあります。キャッシュの期間も、正確なバージョンを含めて 5 分です(正式公開後は 1 年)。本番のデータから参照するのは正式公開後にしてください。
どの URL を使うか
| 用途 | URL |
|---|---|
保存するデータの @context、Link ヘッダー | バージョンの別名 /context/<subject>/v1.jsonld |
| 監査、他のブローカーでの結果の再現 | 正確なバージョン /context/<subject>/v1.0.0.jsonld |
| 検証 | /schema/<subject>/<Type>/v1.json(バージョンの別名)または v1.0.0.json |
バージョンの別名が指す先は、互換性のあるバージョンにしか変わらないので、通常はこれで十分です。監査や結果の再現が要るときは正確なバージョンを使ってください。
サーバーやブローカーは、取得したファイルをキャッシュして使い回せます。バージョンの別名のキャッシュ期間は 5 分なので、互換性のある新しいバージョンは 5 分以内に行き渡ります。正確なバージョンは中身が変わらないので、1 年です(正式公開から。それまでは 5 分)。
約束
- 公開したバージョン付きファイルは変更も削除もしない。
/context/<subject>/v1.0.0.jsonldの中身は永久に同じです。CI はプルリクエストのたびに、公開済みのファイルを main ブランチと公開中のサイトの両方と比べ、変更があれば取り込みません。 - 属性の意味は変えない。 変える必要があるときは新しい属性を足し、古い属性を非推奨にします。
- 型と属性の IRI はドキュメントにつながる。 型の IRI をブラウザで開くと、その型のページが表示されます。たとえば
https://datamodels.jp/ns/transportation/RoadRestrictionです。プログラムが JSON-LD を求めると(Accept: application/ld+json)、語彙が返ります(/vocab/transportation/v1.jsonld)。語彙には、型の定義、ラベル、説明が入っています。
バージョン
バージョンは分野ごとに 1 つで、@context、語彙、JSON Schema が同じ番号になります(例:transportation の 1.0.0)。番号は Semantic Versioning に従います。
| 変更 | 上げる番号 | 例 |
|---|---|---|
| 意味も検証も変わらない修正 | パッチ(1.0.1) | スキーマの説明文の誤字 |
| 互換性のある追加 | マイナー(1.1.0) | 任意の属性やモデルを足す、値の一覧に値を足す |
| 互換性のない変更 | メジャー(2.0.0) | 属性の名前や型を変える、属性や値を消す、任意の属性を必須にする |
新しいバージョンを出しても古いものは残ります。v1.0.0 は同じ URL のままで、バージョンの別名 v1 が最新の 1.x を指します。値の一覧に値を足すのはマイナーです。ただし、すべての値に対応するコードは新しい値を知っておく必要があるので、Pull Request とモデルの注記に書きます。
非推奨
- 属性を置き換えるときは、スキーマとモデルのページで「非推奨」と表示します。少なくとも次のマイナーバージョンまで残し、削除はメジャーバージョンでだけ行います。
- モデルを新しく使わないでほしいときは「非推奨」にします。公開は続き、URL も変わりません。後継があれば、ページと
catalog.jsonに示します(supersededBy)。
ファイルを確かめる
catalog.json の digests には、バージョン付きのファイルごとの SHA-256 ダイジェストがあります。対象は、公開したすべてのバージョンの @context、語彙、JSON Schema です(例:/schema/common/Geometry/v1.0.0.json)。書き方は、Subresource Integrity と同じ sha256-<base64> です。
- 固定する:使うファイルのダイジェストを、自分の設定やロックファイルに書いておきます。読み込むたびに比べると、内容が変わったときに気づけます。ただし、正式公開までのプレリリースの間は、公開したファイルを直すことがあり、そのときはダイジェストも変わります。
- リポジトリと比べる:公開したバージョンのファイルは、GitHub のリポジトリの
models/<subject>/releases/v<version>/にもあります。そこから計算したダイジェストは、配信元の datamodels.jp とは別の経路で確かめた値になります。リポジトリのファイルと URL は、次のように対応します。context.jsonld:/context/<subject>/v<version>.jsonldvocab.jsonld:/vocab/<subject>/v<version>.jsonldschema/<Type>.json:/schema/<subject>/<Type>/v<version>.json
ダイジェストは、次のコマンドで計算できます。一時ファイルに保存してから計算するので、ダウンロードに失敗したときは何も出力しません。一時ファイルは最後に消します。出力の前に sha256- を付けると、digests の値と同じ形になります。
bash
f=$(mktemp)
curl -fsSo "$f" https://datamodels.jp/schema/common/Geometry/v1.0.0.json \
&& openssl dgst -sha256 -binary "$f" | openssl base64 -A
rm -f "$f"ダイジェストは、ファイルと同じサイトから配信されます。手元のコピーやキャッシュが公開されたファイルと同じかは確かめられますが、サイトそのものが書き換えられたときは防げません。そのときは、リポジトリのファイルと比べます。署名はありません。
URL の一覧
| URL | 内容 |
|---|---|
/context/<subject>/vX.Y.Z.jsonld | @context(不変) |
/context/<subject>/vX.jsonld | バージョンの別名(最新の X.y.z) |
/schema/<subject>/<Type>/vX.Y.Z.json | JSON Schema(不変) |
/schema/<subject>/<Type>/vX.json | バージョンの別名 |
/vocab/<subject>/vX.Y.Z.jsonld | 語彙(RDFS: クラス、サブクラス関係、日英ラベル。不変) |
/vocab/<subject>/vX.jsonld | バージョンの別名 |
/examples/<subject>/<Type>/example.json | 例(key-values の形) |
/examples/<subject>/<Type>/example-normalized.jsonld | 例(normalized の形。値型には無い) |
/ns/<subject>/<Term> | 型・属性の IRI(ページにリダイレクト。JSON-LD のクライアントには語彙) |
/mapping/<subject>/<Type>/<name>.yaml | 対応表(他の標準との対応と変換の規則。バージョンなし。URL は変わらず、内容はその時点のモデルに合わせる) |
/adapters/<name>/<subject>/<Type>.<拡張子> | アダプターのファイル:CSV テンプレート(.csv)、Table Schema(.tableschema.json)、AI 用の構造化出力(.ai.json)、PostgreSQL / PostGIS のテーブル(.sql)、GeonicDB の Custom Data Model 定義(.json) |
/catalog.json | プログラム向けの全モデルの一覧(/catalog.schema.json に準拠) |
すべてのファイルは、Access-Control-Allow-Origin: * を付けて配信します。Content-Type は次のとおりです。
.jsonld:application/ld+json- スキーマ:
application/schema+json - 対応表:
application/yaml - CSV テンプレート:
text/csv - SQL のファイル:
application/sql - ほかの
.json(例のファイル、アダプターのファイル、catalog.json):application/json