プレリリース版です。正式公開までは、公開済みのファイルも含めて内容が変わることがあります。
Skip to content

出典: https://datamodels.jp/guide/urls · 文章は CC BY 4.0

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 分)。

v1.0.0v1.1.0v1.2.0v2.0.0公開したバージョン: 変わらないv1.jsonldバージョンの別名: 最新の 1.xv2.jsonld互換性のない変更

約束 ​

  1. 公開したバージョン付きファイルは変更も削除もしない。 /context/<subject>/v1.0.0.jsonld の中身は永久に同じです。CI はプルリクエストのたびに、公開済みのファイルを main ブランチと公開中のサイトの両方と比べ、変更があれば取り込みません。
  2. 属性の意味は変えない。 変える必要があるときは新しい属性を足し、古い属性を非推奨にします。
  3. 型と属性の 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>.jsonld
    • vocab.jsonld:/vocab/<subject>/v<version>.jsonld
    • schema/<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.jsonJSON 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