English
Use with GeonicDB
GeonicDB is an NGSI-LD broker made by Geolonia, the company that runs this catalog. The steps for any broker are in Using the models; this page covers what GeonicDB adds: you can register a model, and GeonicDB then checks every entity of that type against it.
For every model, a ready-made definition is published at https://datamodels.jp/adapters/geonicdb/<subject>/<Type>.json (list by model). It names the model's @context (contextUrl), so registering it is enough for GeonicDB to use the catalog's attribute names.
Registration is optional. What a registered model checks, and what it does not, is below.
Steps
You need a tenant and an API key whose policy allows these requests (API keys, policy binding). The steps use three environment variables:
GEONICDB_BASE_URL(for examplehttps://<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. Register the model (once per tenant). The tenant comes from the API key.
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. Create an entity: the model page's normalized example, as is
# (GeonicDB v0.22.0 or later; see the note below).
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. Query: closed roads only.
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
# Once: where to send requests. With an API key, also export GDB_API_KEY.
geonic config set url "$GEONICDB_BASE_URL"
geonic config set service "$GEONICDB_TENANT"
export GDB_API_KEY="$GEONICDB_API_KEY"
# 1. Register the model (once per tenant).
curl -sSf "$BASE/adapters/geonicdb/$MODEL.json" -o model.json
geonic models create @model.json
# 2. Create an entity: the model page's normalized example, as is
# (GeonicDB v0.22.0 or later; see the note below).
curl -sSf "$BASE/examples/$MODEL/example-normalized.jsonld" -o entity.jsonld
geonic entities create @entity.jsonld
# 3. Query: closed roads only.
geonic entities list --type RoadRestriction \
--query 'restrictionStatus=="closed"' \
--context "$BASE/context/transportation/v1.jsonld"Registering returns
201 Created. If a model of that type already exists, it answers with the errorCustom data model already exists(HTTP 409). GeonicDB answers HTTP 409 from v0.25.0; an older GeonicDB answers HTTP 400. To change a registered model, usePATCH /custom-data-models/<Type>orgeonic models update <Type> @model.json.Decision: the Decision model has VocabProperty and JsonProperty attributes. GeonicDB accepts these two types in a model from v0.23.0; an older GeonicDB answers HTTP 400.
Typed dates: the normalized example writes date-times as
{"@type": "DateTime", "@value": "…"}. GeonicDB accepts this form from v0.22.0, and the examples of Task, Milestone and Project from v0.24.0. With an older GeonicDB, turn the typed dates into strings with jq (for the other models, such as Task, setMODEL, for exampleMODEL=task/Task, and register that model first). Then sendentity.jsonldwith the second command of step 2 (curl -X POST … --data @entity.jsonld; with the 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 and Milestone (
start,due) and Project (start,end) may be a plain date. The model declares them with GeonicDB'sdatetype, which means a date or a date-time (#185). On GeonicDB v0.23.x and older,datemeans the same asdatetime, so a plain date such as"2026-07-11"gets HTTP 400. The Milestone example has a plain date indue, so it fails on v0.23.x and older even after the jq step. Your own data can send the plain string, as in"validFrom": {"type": "Property", "value": "2026-07-08T09:00:00+09:00"}.GeonicDB CLI: geonicdb-cli (
npm install -g @geolonia/geonicdb-cli@0.26.1). Logged in as a tenant admin withgeonic auth login, it needs no API key or policy. A saved login is used before--api-key, so rungeonic auth logoutfirst when you use an API key. Add--dry-runto any command to see the request without sending it.For your own data, put the @context in the body (
application/ld+json) or sendapplication/jsonwith theLinkheader, never both. The tenant header isNGSILD-Tenant(multi-tenancy).
What a registered model checks
GeonicDB checks every entity of the type when it is created or changed, also in batches and through NGSIv2:
- the required attributes are there;
- each value has the right type (text, number, whole number, true or false, list, object, GeoJSON, URI, date and date-time in RFC 3339) and follows the rules: length, minimum and maximum, pattern, allowed values:
- a VocabProperty's allowed terms are compared as full IRIs, expanded with the @context you send, so
dpv:HumanNotInvolvedandhttps://w3id.org/dpv#HumanNotInvolvedare the same term;
- a VocabProperty's allowed terms are compared as full IRIs, expanded with the @context you send, so
- there are no attributes the model does not know (the catalog's definitions do not allow them);
- combinations that must be unique are unique, if the definition declares them.
It does not check:
- the values inside a list, such as allowed values or a minimum number of items: only that the value is a list (the catalog's JSON Schema checks them, for example during
datamodels convert); - whether an attribute is sent as a Property or a Relationship, or which type a Relationship points to;
- entities of a type that has no registered model: they are stored as they are;
- the other types of an entity with several types: only the first type is checked;
- entities that existed before the model was registered or changed. To see how a change would affect them, send it with
PATCH /custom-data-models/<Type>?dryRun=true(GeonicDB v0.17.0 or later) orgeonic models update <Type> @model.json --api-dry-run(geonicdb-cli 0.25.0 or later): nothing changes, and the answer says how many entities would break the model, with examples.
Your own attributes
If the model fits but you need a few attributes of your own, write an extension, an @context that adds them (Adding attributes), host it, and register a definition that has the catalog's attributes and yours. Your attributes are then checked like the others. If they are useful beyond your project, propose them to the catalog.
The export script below (adapters/geonicdb/export.mjs) is in this catalog's repository. Get it first; you need Node.js 24 or later:
bash
git clone https://github.com/geolonia/datamodels && cd datamodels && npx pnpm installExporting a definition with your attributes
Write an extension file keyed by type and export with it. Redefining a catalog attribute is an error.
json
{
"RoadRestriction": {
"contextUrl": "https://example.com/context/acme-transportation.jsonld",
"propertyDetails": {
"patrolRoute": {
"ngsiType": "Property",
"valueType": "string",
"example": "A-3",
"description": "Patrol route",
"@context": "https://example.com/ns/acme/patrolRoute"
}
}
}
}bash
node adapters/geonicdb/export.mjs transportation \
--type RoadRestriction --extend ./acme.json --out ./outTo accept unknown attributes without checking them instead, export with --allow-additional.
Different type or attribute names in your tenant
A tenant that needs a prefix on its type names (for example when several projects share it and policies match on the type name) can export prefixed definitions. The attribute names and their meaning stay the catalog's.
bash
node adapters/geonicdb/export.mjs transportation \
--type-prefix Acme --out ./outWith your own names for a type or an attribute (Your own names), register the model under your names and point contextUrl at your @context. The export script renames in one go; each attribute keeps the catalog's meaning:
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