Pre-release. Until the official launch, content may change, including published files.
Skip to content

Source: https://datamodels.jp/en/guide/geonicdb · Text CC BY 4.0

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.

datamodels.jpthe model's definition (.json) and @contextGeonicDB (your tenant)the registered model: rules for the typeYour applicationcreates and queries entities① registerreads the @context② create: checked, stored③ query

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 example 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. 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 error Custom 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, use PATCH /custom-data-models/<Type> or geonic 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, set MODEL, for example MODEL=task/Task, and register that model first). Then send entity.jsonld with the second command of step 2 (curl -X POST … --data @entity.jsonld; with the 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 and Milestone (start, due) and Project (start, end) may be a plain date. The model declares them with GeonicDB's date type, which means a date or a date-time (#185). On GeonicDB v0.23.x and older, date means the same as datetime, so a plain date such as "2026-07-11" gets HTTP 400. The Milestone example has a plain date in due, 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 with geonic auth login, it needs no API key or policy. A saved login is used before --api-key, so run geonic auth logout first when you use an API key. Add --dry-run to any command to see the request without sending it.

  • For your own data, put the @context in the body (application/ld+json) or send application/json with the Link header, never both. The tenant header is NGSILD-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:HumanNotInvolved and https://w3id.org/dpv#HumanNotInvolved are the same term;
  • 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) or geonic 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 install
Exporting 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 ./out

To 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 ./out

With 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