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

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

自分のサイトで公開する ​

自分のデータモデルを、自分のサイト（ノード）で公開する手順です。最初のコマンドから、自分のドメインで公開するまでを順に説明します。そもそも自分のサイトが要るかどうかは、自分のデータモデルで確かめてください。

できあがるのは models.geolonia.com のようなサイトです。catalog.json、@context、JSON Schema、語彙、例、型と属性ごとの説明のページがそろいます。

用意するもの ​

  • Node.js 24 以降。コマンドは npx で実行するので、インストールは要りません。
  • GitHub のアカウント（GitHub Pages で公開するため）。
  • 自分で管理できるドメインかサブドメイン（models.example.org など。推奨。手順 5）。

1. ノードを作る ​

bash
npx github:geolonia/datamodels-toolkit#v0.2.1 init my-models
cd my-models

init がいくつか質問します。

  • ベース URL： ノードを置く場所です（例：https://models.example.org）。ノードが公開するすべての IRI に入るので、公開した後は変えられません。https://<アカウント>.github.io/<リポジトリ> も使えますが、IRI が GitHub のアカウント名に依存します。
  • 言語： ja,en など。1 つでも構いません。
  • 公開者： 組織の名前とウェブサイトです。
  • ライセンス： CC0-1.0 なら、だれでも条件なしにモデルを使えます（このカタログと同じです）。
  • 最初のサブジェクト： 1 つの @context を共有するモデルのまとまりです（例：road）。この名前も IRI に入ります。

init は、設定の node.yaml、サブジェクトの models/road/、README、公開用のワークフローを書き出します。既存のリポジトリで実行すると、足りないファイルだけを足します。

GitHub CLI（gh）があれば、--github my-org/my-models を付けて実行できます。init がその名前で公開リポジトリを作り、ファイルを push して GitHub Pages を有効にします（手順 4）。

2. モデルを足す ​

bash
npx github:geolonia/datamodels-toolkit#v0.2.1 add road/RoadPatrol

このカタログのモデルから始めるときは、extend を使います。カタログのモデルのスキーマをコピーし、その @context を取り込み、土台にしたモデルを記録します。そのため、check が名前と意味を変えていないかを検査できます。そのうえで、下のように自分の属性を足します。--subclass を付けると、独自の IRI を持つサブタイプになります。

bash
npx github:geolonia/datamodels-toolkit#v0.2.1 extend task/Task road/RoadTask

models/road/RoadPatrol/ に schema.json、catalog.yaml、examples/example.json ができます。サブジェクトの @context には型 RoadPatrol が入ります。属性は、1 つにつき 3 か所に書きます。まず models/road/RoadPatrol/schema.json の properties に書き、IRI は x-iri に入れます。

json
"route": {
  "type": "string",
  "description": "The route patrolled",
  "x-iri": "https://models.example.org/ns/road#route"
}

次に models/road/context.jsonld の @context に、同じ IRI で書きます。

json
"route": "road:route"

最後に、models/road/RoadPatrol/catalog.yaml へノードの言語ごとの説明を書きます。

yaml
attributes:
  route: { ja: 巡回したルート, en: The route patrolled }

examples/example.json にも値を入れてください（"route": "A-3"）。catalog.yaml と models/road/subject.yaml のタイトルと説明も、自分の言葉に書き換えます。名前や説明の付け方は、このカタログのモデルのルールが参考になります。

3. 検査してビルドする ​

bash
npx github:geolonia/datamodels-toolkit#v0.2.1 check
npx github:geolonia/datamodels-toolkit#v0.2.1 build

check は、すべてのスキーマと例を検査します。build はサイトを _site/ に書き出すので、_site/index.html を開いて確かめられます。GitHub では、Pull Request のたびにワークフローが同じ検査をします。

4. GitHub Pages で公開する ​

--github を付けて始めた場合は、リポジトリができています。モデルをコミットして push してください。

そうでない場合は、GitHub で空のリポジトリを作り、フォルダーをその main ブランチに push します。そのうえで、リポジトリの Settings → Pages で、Source を GitHub Actions にします。

これで、main への push のたびにノードがビルドされ、公開されます。ドメインを設定するまでは、https://<アカウント>.github.io/<リポジトリ>/ で表示されます。

5. 自分のドメインで公開する ​

  1. DNS で、サブドメインから <アカウント>.github.io への CNAME レコードを追加します（例：models → my-org.github.io）。
  2. Settings → Pages の Custom domain にドメインを入力します。GitHub が証明書を用意したら（数分から 1 時間ほど）、Enforce HTTPS を有効にします。

アカウントか組織でドメインを確認しておくと、ほかの人がそのドメインでサイトを公開できなくなります。

公開した後でモデルを変える ​

公開したバージョンは変えられません。@context を指定したデータは、その内容を前提にしているからです。check は公開済みのファイルと比べ、変わるファイルがあれば失敗します。

変える前に、公開したバージョンをサイトに残す手続きをします。release が、その @context、語彙、スキーマを models/road/releases/ に保存するので、コミットしてください。公開済みのファイルと違えば、release は止まります。

bash
npx github:geolonia/datamodels-toolkit#v0.2.1 release road

そのうえでモデルを変え、subject.yaml の version を上げます（URL とバージョン）。サイトには両方のバージョンが残ります。

すべてのコマンドとオプション：datamodels-toolkit（英語）