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

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

使い方 ​

各モデルのページには、@context(各属性の意味)、JSON Schema(正しいデータの形)、例の 3 つがあります。どれも普通の URL で公開しているので、特定の製品がなくても使えます。モデルは分野ごとにまとまっています。分野は、関係するモデルのまとまりで、名前空間とバージョンを持ちます(disaster、transportation など)。データの中では、バージョンの別名の URL(…/v1.jsonld、…/v1.json)を使います。互換性のある最新のバージョンを指す URL です。使い分けはURL とバージョンで、言葉の意味は用語で説明しています。

使い方は 3 通りです。どれか 1 つだけでも、組み合わせても使えます。

NGSI-LD を読まないツール(表計算ソフト、AI、PostgreSQL)向けのファイルもあります。他のツールに書き出すを見てください。

datamodels.jp のモデル@context・JSON Schema・例JSON を検証するJSON Schema でNGSI-LD ブローカーに送る@context 付きの normalized の形でLinked Data として使う@context で JSON を RDF に

以下では通行規制(RoadRestriction)を例にしていますが、URL を替えれば、どのモデルでも同じように使えます。

JSON を検証する ​

JSON Schema で確認するのは、属性名と値だけの単純な形のデータです。この形を key-values の形と呼びます。住所やジオメトリなど、ほかのスキーマを参照している部分も、自動で取得して確認します。

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 はカタログの x-* 注釈を受け入れる。
// loadSchema は参照先のスキーマを取得する。
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] がないと URI と日時の形式を検証しない)
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")

# 参照先のスキーマ(住所、ジオメトリ)は、
# 使われたときに取得する。
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(または 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

許されていない値があると、どの属性のどこが違うかが表示されます。

NGSI-LD ブローカーに送る ​

NGSI-LD のブローカーには、通常は normalized の形で送ります。この形では、各属性が自分の種類も示します。値を持つ Property なのか、別のエンティティを指す Relationship なのか、といった種類です。モデルのページには両方の形の例があるので、normalized の例はそのまま送れます。

bash
BROKER=http://localhost:1026   # ブローカーの URL
BASE=https://datamodels.jp
MODEL=transportation/RoadRestriction
curl -sSf "$BASE/examples/$MODEL/example-normalized.jsonld" -o entity.jsonld

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

# 検索: 通行止め中のものだけ
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"

@context の渡し方は 2 通りです。ボディに入れて application/ld+json で送るか、ボディには入れずに application/json と Link ヘッダーで送ります。ヘッダーはモデルのページにあります。複数のテナントを持つブローカーでは NGSILD-Tenant ヘッダーでテナントを指定します。認証の方法はブローカーごとに違います。

自分のデータを normalized の形にする決まりと例は、normalized の形にあります。

Linked Data として使う ​

@context を付けると、普通の JSON が JSON-LD になり、Linked Data のツールが使う RDF に変換できます。各属性には世界で一意の名前(IRI)が付くので、名前が違っても IRI が同じなら意味は同じです(独自の名前で使う)。

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`,
);
// 普通の JSON に context を付けると Linked Data になる。
entity['@context'] = [
  `${base}/context/transportation/v1.jsonld`,
  // id と type の対応:
  'https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld',
];

// 既定のローダーの代わりに fetch を使う(どの環境でも動く)。
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()
# 普通の JSON に context を付けると Linked Data になる。
entity["@context"] = [
    f"{BASE}/context/transportation/v1.jsonld",
    # id と type の対応:
    "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld",
]

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

結果の一部です。N-Quads は、RDF をテキストで書く形式です。1 行が 1 つの文です。どの行も「エンティティ(1 つ目)が、属性(2 つ目、IRI)として、値(3 つ目)を持つ」と読みます。

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> "靖国通り" .

各分野は、語彙(/vocab/<subject>/v1.0.0.jsonld、RDFS)も公開しています。語彙には、型と属性の名前と説明が日本語と英語で入っています。ほかの語彙から取り入れた属性(schema.org の address など)の説明は、それぞれの提供元にあります。

他のツールで使う ​

NGSI-LD を読まないツール向けのファイルも、エンティティのモデルのページ(Geometry などの値型を除く)のダウンロードの行にあります。それぞれの手順を、1 つの例で示しています。

自分のサイトのモデルでこれらのファイルを作るには、他のツールに書き出すを見てください。