日本語
GeonicDB で使う
GeonicDB は、このカタログを運営している Geolonia の NGSI-LD ブローカーです。どのブローカーにも共通の手順は使い方にあります。このページでは、GeonicDB ならではの機能を説明します。GeonicDB にはモデルを登録できます。登録すると、その型のエンティティはすべてモデルで検証されます。
モデルごとに、登録用の定義を https://datamodels.jp/adapters/geonicdb/<subject>/<Type>.json で公開しています(モデルごとの一覧)。定義にはモデルの @context(contextUrl)が入っているので、登録するだけで、GeonicDB でカタログの属性名がそのまま使えます。
登録しなくても使えます。登録したモデルが何を検証し、何を検証しないかは、下の節で説明します。
手順
テナントと、これらの操作を許すポリシーを付けた API キーが要ります(API キー、ポリシーバインディング)。使う環境変数は次の 3 つです。
GEONICDB_BASE_URL(例:https://<your-deployment>.geonicdb.jp)GEONICDB_TENANTGEONICDB_API_KEY
bash
BASE=https://datamodels.jp
MODEL=transportation/RoadRestriction
KEY="x-api-key: $GEONICDB_API_KEY"
TENANT="NGSILD-Tenant: $GEONICDB_TENANT"
# 1. モデルを登録する(テナントごとに 1 回)。テナントは API キーで決まります。
curl -sSf "$BASE/adapters/geonicdb/$MODEL.json" -o model.json
curl -X POST "$GEONICDB_BASE_URL/custom-data-models" \
-H "Content-Type: application/json" -H "$KEY" \
--data @model.json
# 2. エンティティを作成する。モデルのページの normalized の例を、
# そのまま送ります(GeonicDB v0.22.0 以降。下の注を参照)。
curl -sSf "$BASE/examples/$MODEL/example-normalized.jsonld" -o entity.jsonld
curl -X POST "$GEONICDB_BASE_URL/ngsi-ld/v1/entities" \
-H "Content-Type: application/ld+json" -H "$KEY" -H "$TENANT" \
--data @entity.jsonld
# 3. 検索する(通行止めだけ)。
CONTEXT="$BASE/context/transportation/v1.jsonld"
REL='rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"'
curl -G "$GEONICDB_BASE_URL/ngsi-ld/v1/entities" \
--data-urlencode 'type=RoadRestriction' \
--data-urlencode 'q=restrictionStatus=="closed"' \
-H "Accept: application/ld+json" -H "Link: <$CONTEXT>; $REL" \
-H "$KEY" -H "$TENANT"bash
BASE=https://datamodels.jp
MODEL=transportation/RoadRestriction
# 最初に 1 回:送り先。API キーで使うときは GDB_API_KEY も設定します。
geonic config set url "$GEONICDB_BASE_URL"
geonic config set service "$GEONICDB_TENANT"
export GDB_API_KEY="$GEONICDB_API_KEY"
# 1. モデルを登録する(テナントごとに 1 回)。
curl -sSf "$BASE/adapters/geonicdb/$MODEL.json" -o model.json
geonic models create @model.json
# 2. エンティティを作成する。モデルのページの normalized の例を、
# そのまま送ります(GeonicDB v0.22.0 以降。下の注を参照)。
curl -sSf "$BASE/examples/$MODEL/example-normalized.jsonld" -o entity.jsonld
geonic entities create @entity.jsonld
# 3. 検索する(通行止めだけ)。
geonic entities list --type RoadRestriction \
--query 'restrictionStatus=="closed"' \
--context "$BASE/context/transportation/v1.jsonld"登録すると
201 Createdが返ります。同じ型名のモデルが既にあれば、Custom data model already existsのエラー(HTTP 409)になります。GeonicDB は、v0.25.0 からこのエラーを HTTP 409 で返します。それより古い GeonicDB では HTTP 400 です。登録したモデルを変えるときはPATCH /custom-data-models/<Type>かgeonic models update <Type> @model.jsonを使います。Decision: Decision のモデルには、VocabProperty と JsonProperty の属性があります。GeonicDB は、v0.23.0 からこの 2 つの型をモデルで受け付けます。それより古い GeonicDB では、登録が HTTP 400 のエラーになります。
型付きの日時: normalized の例では、日時を
{"@type": "DateTime", "@value": "…"}の形で書いています。GeonicDB は、v0.22.0 からこの形を受け付けます。Task・Milestone・Project の例は、v0.24.0 からそのまま受け付けます。それより古い GeonicDB では、jq で日時を文字列に直します。Task などでは、MODEL=task/TaskのようにMODELを変え、先にそのモデルを登録します。そのあと手順 2 の 2 つ目のコマンド(curl -X POST … --data @entity.jsonld)で送ります。CLI ではgeonic entities create @entity.jsonldです。bashcurl -sSf "$BASE/examples/$MODEL/example-normalized.jsonld" -o typed.jsonld jq 'walk(if type == "object" and has("@value") then .["@value"] else . end)' \ typed.jsonld > entity.jsonldTask と Milestone の
start・due、Project のstart・endは、日付だけの値になることもあります。モデルでは、日付または日時を表す GeonicDB のdate型で定義しています(#185)。v0.23.x 以前の GeonicDB ではdateがdatetimeと同じ意味なので、日付だけの値("2026-07-11")は HTTP 400 になります。Milestone の例はdueが日付だけなので、jq で直しても v0.23.x 以前には送れません。自分のデータでは、"validFrom": {"type": "Property", "value": "2026-07-08T09:00:00+09:00"}のように文字列で送れます。GeonicDB CLI: geonicdb-cli(
npm install -g @geolonia/geonicdb-cli@0.26.1)。geonic auth loginでテナント管理者としてログインすれば、API キーもポリシーも要りません。保存したログイン情報は--api-keyより優先されるので、API キーで使うときは、先にgeonic auth logoutを実行してください。どのコマンドも、--dry-runを付けると、実際には送らずにリクエストの内容を表示します。自分のデータを送るときは、@context をボディに入れて(
application/ld+json)送るか、application/jsonとLinkヘッダーで送ります。両方を同時には使いません。テナントはNGSILD-Tenantヘッダーで指定します(マルチテナンシー)。
登録したモデルが検証すること
GeonicDB は、その型のエンティティを作成・変更するたびに検証します。まとめて送るとき(バッチ)や NGSIv2 で送るときも同じです。
- 必須の属性があること
- 値の型が合っていること(文字列、数値、整数、真偽値、リスト、オブジェクト、GeoJSON、URI、RFC 3339 の日付と日時)と、長さ、最小値・最大値、パターン、許される値のルールを守っていること
- VocabProperty の許される値は、送った @context で完全な IRI に直して比べること(
dpv:HumanNotInvolvedと書いても、完全な IRI で書いても同じ値)
- VocabProperty の許される値は、送った @context で完全な IRI に直して比べること(
- モデルに無い属性が含まれていないこと(カタログの定義では許していません)
- 一意でなければならない組み合わせが一意であること(定義で宣言していれば)
検証しないこと:
- リストの中の値(許される値、最低の個数など)。リストであることだけを検証します(カタログの JSON Schema は中の値も検証します。
datamodels convertの変換時など)。 - 属性が Property と Relationship のどちらで送られたか、Relationship がどの型を指しているか。
- モデルを登録していない型のエンティティ。そのまま保存されます。
- 型を複数持つエンティティの 2 つめ以降の型。検証するのは 1 つめの型だけです。
- モデルを登録・変更する前からあるエンティティ。変更の影響は、試しに実行して確かめられます。何も変えずに、モデルに合わなくなるエンティティの数と例が返ります。
- API:
PATCH /custom-data-models/<Type>?dryRun=true(GeonicDB v0.17.0 以降)。 - CLI:
geonic models update <Type> @model.json --api-dry-run(geonicdb-cli 0.25.0 以降)。
- API:
独自の属性
モデルはほぼ合うものの、独自の属性がいくつか要るときは、その属性を足した @context(拡張)を作って公開します(属性を足す)。そのうえで、カタログの属性と自分の属性の両方を含む定義を登録します。独自の属性も、ほかの属性と同じように検証されます。ほかの案件でも役に立つ属性なら、カタログに提案してください。
下の書き出しスクリプト(adapters/geonicdb/export.mjs)は、このカタログのリポジトリにあります。先にリポジトリを取得します。Node.js 24 以降が要ります。
bash
git clone https://github.com/geolonia/datamodels && cd datamodels && npx pnpm install独自の属性を入れた定義を書き出す
型名をキーにした拡張ファイルを用意し、定義を書き出します。カタログの属性を定義し直そうとすると、エラーになります。
json
{
"RoadRestriction": {
"contextUrl": "https://example.com/context/acme-transportation.jsonld",
"propertyDetails": {
"patrolRoute": {
"ngsiType": "Property",
"valueType": "string",
"example": "A-3",
"description": "巡回ルート",
"@context": "https://example.com/ns/acme/patrolRoute"
}
}
}
}bash
node adapters/geonicdb/export.mjs transportation \
--type RoadRestriction --extend ./acme.json --out ./out未知の属性を検証せずに受け付けるだけなら、--allow-additional で書き出します。
テナント内で型名や属性名を変える
型名に接頭辞を付けたいテナント(複数の案件が共有し、ポリシーを型名で分けているときなど)は、接頭辞付きの定義を書き出せます。属性名とその意味はカタログのままです。
bash
node adapters/geonicdb/export.mjs transportation \
--type-prefix Acme --out ./out型や属性を独自の名前で使う(独自の名前で使う)なら、自分の名前で登録し、contextUrl に自分の @context を指定します。書き出しスクリプトが名前をまとめて置き換えます。各属性の意味は、カタログと同じです。
bash
CONTEXT=https://example.com/context/city-disaster.jsonld
node adapters/geonicdb/export.mjs task --type Project --type-name SaigaiTaiou \
--context-url "$CONTEXT" --out ./out
node adapters/geonicdb/export.mjs task --type Task \
--rename assignee=taiouHan \
--context-url "$CONTEXT" --out ./out