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

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

Using the models ​

Every model page gives three things: the @context (what each attribute means), the JSON Schema (what valid data looks like) and examples. They are plain URLs, so no particular product is needed. Models come in subjects: a subject is a group of related models with its own namespace and versions, such as disaster or transportation. Use the version alias URLs (…/v1.jsonld, …/v1.json) in your data: they point to the latest compatible version. Which URL to use when is in URLs and versions; what the words mean is in Terms.

There are three ways to use a model, and you can use one, two or all three:

For tools that do not read NGSI-LD (a spreadsheet, an AI model, PostgreSQL) there are files too: see Exporting to other tools.

A model on datamodels.jp@context · JSON Schema · examplesValidate JSONwith the JSON SchemaSend it to an NGSI-LD brokerin the normalized form, with the @contextUse it as linked datathe @context turns JSON into RDF

The examples use road restriction (RoadRestriction); swap the URLs for any other model.

Validate JSON ​

The JSON Schema checks data in the key-values form: attribute names with plain values. Parts that refer to other schemas, such as the address or the geometry, are fetched and checked too.

js
// npm install ajv ajv-formats
import Ajv2020 from 'ajv/dist/2020.js';
import addFormats from 'ajv-formats';

const base = 'https://datamodels.jp';
const model = 'transportation/RoadRestriction';
const getJson = async (url) => (await fetch(url)).json();

const schema = await getJson(`${base}/schema/${model}/v1.0.0.json`);
const entity = await getJson(`${base}/examples/${model}/example.json`);

// strict: false accepts the catalog's x-* annotations.
// loadSchema fetches the schemas this one refers to.
const ajv = new Ajv2020({ strict: false, loadSchema: getJson });
addFormats(ajv);
const validate = await ajv.compileAsync(schema);
console.log(validate(entity) ? 'valid' : validate.errors);
python
# pip install "jsonschema[format]" requests
# ([format] is needed to check URIs and dates)
import requests
from jsonschema import Draft202012Validator
from referencing import Registry, Resource

BASE = "https://datamodels.jp"
MODEL = "transportation/RoadRestriction"

def get(url):
    return requests.get(url, timeout=30).json()

schema = get(f"{BASE}/schema/{MODEL}/v1.0.0.json")
entity = get(f"{BASE}/examples/{MODEL}/example.json")

# The registry fetches referenced schemas (address, geometry)
# when they are first used.
registry = Registry(retrieve=lambda url: Resource.from_contents(get(url)))
validator = Draft202012Validator(
    schema,
    registry=registry,
    format_checker=Draft202012Validator.FORMAT_CHECKER,
)
errors = [e.message for e in validator.iter_errors(entity)]
print(errors or "valid")
bash
# pipx install check-jsonschema (or uvx check-jsonschema ...)
BASE=https://datamodels.jp
MODEL=transportation/RoadRestriction
curl -sSf "$BASE/examples/$MODEL/example.json" -o entity.json
check-jsonschema --schemafile "$BASE/schema/$MODEL/v1.0.0.json" entity.json

When a value is not allowed, the output names the attribute and what is wrong.

Send it to an NGSI-LD broker ​

NGSI-LD brokers usually take the normalized form, in which each attribute also says what kind it is (a Property with a value, a Relationship pointing to another entity, and so on). Every model page has the example in both forms, so the normalized example can be sent as it is:

bash
BROKER=http://localhost:1026   # your broker's URL
BASE=https://datamodels.jp
MODEL=transportation/RoadRestriction
curl -sSf "$BASE/examples/$MODEL/example-normalized.jsonld" -o entity.jsonld

# Create
curl -X POST "$BROKER/ngsi-ld/v1/entities" \
  -H "Content-Type: application/ld+json" \
  --data @entity.jsonld

# 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 "$BROKER/ngsi-ld/v1/entities" \
  --data-urlencode 'type=RoadRestriction' \
  --data-urlencode 'q=restrictionStatus=="closed"' \
  -H "Accept: application/ld+json" \
  -H "Link: <$CONTEXT>; $REL"

Put the @context in the body and send application/ld+json, or leave it out and send application/json with a Link header (the model page shows it). Brokers with several tenants take the tenant in the NGSILD-Tenant header; authentication differs from broker to broker.

To put your own data into the normalized form, see The normalized form: the rules, with an example.

Use it as linked data ​

Adding the @context turns plain JSON into JSON-LD, which converts to RDF, the format of linked data tools. Every attribute then has a globally unique name (an IRI), so data written under other names means the same when the IRI is the same (Your own names).

js
// npm install jsonld
import jsonld from 'jsonld';

const base = 'https://datamodels.jp';
const getJson = async (url) => (await fetch(url)).json();
const entity = await getJson(
  `${base}/examples/transportation/RoadRestriction/example.json`,
);
// Plain JSON becomes linked data by adding the catalog context.
entity['@context'] = [
  `${base}/context/transportation/v1.jsonld`,
  // maps id and type:
  'https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld',
];

// fetch replaces the default document loader, so this runs anywhere.
const documentLoader = async (url) => ({
  documentUrl: url,
  document: await getJson(url),
});
const nquads = await jsonld.toRDF(entity, {
  format: 'application/n-quads',
  documentLoader,
});
console.log(nquads);
python
# pip install pyld requests
import requests
from pyld import jsonld

BASE = "https://datamodels.jp"
url = f"{BASE}/examples/transportation/RoadRestriction/example.json"
entity = requests.get(url, timeout=30).json()
# Plain JSON becomes linked data by adding the catalog context.
entity["@context"] = [
    f"{BASE}/context/transportation/v1.jsonld",
    # maps id and type:
    "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld",
]

print(jsonld.to_rdf(entity, {"format": "application/n-quads"}))

Part of the output, in N-Quads: RDF written as plain text, one statement per line. Each line says that the entity (first) has an attribute (second, its IRI) with a value (third):

text
<urn:ngsi-ld:RoadRestriction:0001> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <https://datamodels.jp/ns/transportation/RoadRestriction> .
<urn:ngsi-ld:RoadRestriction:0001> <https://datamodels.jp/ns/transportation/restrictionStatus> "closed" .
<urn:ngsi-ld:RoadRestriction:0001> <https://smartdatamodels.org/dataModel.Transportation/roadName> "靖国通り" .

Each subject also publishes a vocabulary (/vocab/<subject>/v1.0.0.jsonld, RDFS) with the Japanese and English names and descriptions of its types and attributes. Attributes borrowed from other vocabularies, such as schema.org's address, are described by their own publishers.

With other tools ​

The page of each entity model (not of value types such as Geometry) also has files for tools that do not read NGSI-LD, in its Download row. Short recipes, each with one worked example:

To make these files for the models of your own site, see Exporting to other tools.