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

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

GeonicDB で使う ​

GeonicDB は、このカタログを運営している Geolonia の NGSI-LD ブローカーです。どのブローカーにも共通の手順は使い方にあります。このページでは、GeonicDB ならではの機能を説明します。GeonicDB にはモデルを登録できます。登録すると、その型のエンティティはすべてモデルで検証されます。

datamodels.jpモデルの定義(.json)と @contextGeonicDB(自分のテナント)登録したモデル: その型のルール自分のアプリエンティティを作成・検索① 登録@context を参照② 作成: 検証して保存③ 検索

モデルごとに、登録用の定義を https://datamodels.jp/adapters/geonicdb/<subject>/<Type>.json で公開しています(モデルごとの一覧)。定義にはモデルの @context(contextUrl)が入っているので、登録するだけで、GeonicDB でカタログの属性名がそのまま使えます。

登録しなくても使えます。登録したモデルが何を検証し、何を検証しないかは、下の節で説明します。

手順 ​

テナントと、これらの操作を許すポリシーを付けた API キーが要ります(API キー、ポリシーバインディング)。使う環境変数は次の 3 つです。

  • GEONICDB_BASE_URL(例:https://<your-deployment>.geonicdb.jp)
  • GEONICDB_TENANT
  • GEONICDB_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 です。

    bash
    curl -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.jsonld

    Task と 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 で書いても同じ値)
  • モデルに無い属性が含まれていないこと(カタログの定義では許していません)
  • 一意でなければならない組み合わせが一意であること(定義で宣言していれば)

検証しないこと:

  • リストの中の値(許される値、最低の個数など)。リストであることだけを検証します(カタログの 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 以降)。

独自の属性 ​

モデルはほぼ合うものの、独自の属性がいくつか要るときは、その属性を足した @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