English
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:
- Validate JSON: check data from an API, a form or a CSV file against the JSON Schema.
- Send it to an NGSI-LD broker: store and query the data in any broker that speaks the standard NGSI-LD API.
- Use it as linked data: add the @context and every attribute gets a globally unique name (an IRI).
For tools that do not read NGSI-LD (a spreadsheet, an AI model, PostgreSQL) there are files too: see Exporting to other tools.
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.jsonWhen 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:
- Using a spreadsheet (CSV): fill in the CSV template, check it with
frictionless validate, and convert it into entities. - Using PostgreSQL / PostGIS: create the model's table with its constraints, add a row, and query by distance.
- Extracting data with AI: give the AI schema to an AI model to take an entity out of an e-mail or a PDF.
To make these files for the models of your own site, see Exporting to other tools.