English
Adding attributes
Often a catalog model fits, but your system needs a few more attributes. You do not need a new model, and you do not copy the catalog: you publish a small @context of your own that takes the catalog's @context and adds only your attributes. This is called an extension (technically, a profile of the model).
If only the names differ, or no model fits, the diagram in the Guides shows which page to read.
Extension builder
The easiest way is the extension builder. Pick the model and enter your attributes; you get two files:
- @context: imports the catalog
@contextby URL and defines only your attributes, so the catalog attributes keep their meaning. It is written as in the next section. - JSON Schema: validates the catalog attributes and yours. It is a copy of the catalog schema at one version, so it does not follow new minor versions of the catalog (When the catalog gets new attributes).
Use a namespace under a domain you control. If an attribute would be useful to many systems, please propose it to the catalog (link below the builder). What you enter stays on this page and is not sent anywhere, except when you open the link to the proposal form: to fill in the form, it sends to GitHub the model's type and, for each attribute you named, its name, NGSI-LD type, value type and format, whether it is required, and your description.
Your attributes
Your @context
{
"@context": [
"https://datamodels.jp/context/transportation/v1.jsonld",
{
"acme": "https://example.com/ns/acme/",
"patrolRoute": "acme:patrolRoute"
}
]
}JSON Schema (the catalog attributes plus yours)
The catalog schemas are closed (additionalProperties: false), so a schema that only references them cannot add attributes. This one starts from https://datamodels.jp/schema/transportation/RoadRestriction/v1.0.0.json; generate it again when you move to a new version, and replace $id with your own URL.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://example.com/schema/acme/RoadRestriction.json",
"title": "RoadRestriction (acme)",
"description": "One road restriction, including closures: road name, regulated section as a point, line or area, status and category.",
"x-license-url": "https://datamodels.jp/LICENSE-CONTENT",
"x-model-tags": "road, transportation, Japan",
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uri",
"description": "Entity id (URN)"
},
"type": {
"type": "string",
"const": "RoadRestriction",
"description": "Entity type"
},
"@context": {
"description": "JSON-LD context of the entity, optional: a context URL or a list of context URLs",
"oneOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "array",
"items": {
"type": "string",
"format": "uri"
},
"minItems": 1
}
]
},
"roadName": {
"description": "Road name",
"type": "string",
"x-ngsi": {
"type": "Property"
},
"x-iri": "https://smartdatamodels.org/dataModel.Transportation/roadName"
},
"roadType": {
"description": "Road class by the Road Act (道路法第3条): expressway (高速自動車国道), nationalRoad (一般国道), prefecturalRoad (都道府県道), municipalRoad (市町村道), or other for a road outside the Act (農道, 林道, private road). A motorway designation (自動車専用道路) is not a class of its own: give the class of the road it is on",
"type": "string",
"enum": [
"expressway",
"nationalRoad",
"prefecturalRoad",
"municipalRoad",
"other"
],
"x-ngsi": {
"type": "Property"
},
"x-iri": "https://datamodels.jp/ns/transportation/roadType"
},
"address": {
"$ref": "https://datamodels.jp/schema/common/JapaneseAddress/v1.0.0.json",
"description": "Address of the location, as a JapaneseAddress value (common subject)",
"x-ngsi": {
"type": "Property",
"model": "https://datamodels.jp/ns/common/JapaneseAddress"
},
"x-iri": "https://schema.org/address"
},
"location": {
"$ref": "https://datamodels.jp/schema/common/Geometry/v1.0.0.json",
"description": "The regulated section, as a GeoJSON geometry. A point for a single-spot restriction, a LineString for a section, a polygon for an area, matching the point/line/area regulation forms (点規制・線規制・面規制) of the NPA's traffic regulation data format (交通規制情報(拡張版標準フォーマット)説明書 Ver: k_2.1, JARTIC, 2025-01-20)",
"x-ngsi": {
"type": "GeoProperty",
"model": "https://datamodels.jp/ns/common/Geometry"
},
"x-iri": "https://uri.etsi.org/ngsi-ld/location"
},
"restrictionLength": {
"type": "number",
"minimum": 0,
"description": "Length of the regulated section in metres, for a line. The NPA format (距離・延長, item 133) and EEI (距離・延長) carry it; the geometry alone may be simplified",
"x-ngsi": {
"type": "Property"
},
"x-iri": "https://datamodels.jp/ns/transportation/restrictionLength"
},
"maximumAllowedWeight": {
"type": "number",
"minimum": 0,
"description": "Weight limit in kilograms: vehicles heavier than this may not pass (for example 4000 when the source limit is 4 t). The same term as Smart Data Models RoadSegment; the NPA format gives it in tonnes (制限重量, item 135). Whether it is gross weight or payload follows the source; keep its wording in statusLabel",
"x-ngsi": {
"type": "Property"
},
"x-iri": "https://smartdatamodels.org/dataModel.Transportation/maximumAllowedWeight"
},
"restrictionStatus": {
"description": "Normalised restriction state, the value space of Smart Data Models RoadSegment.status: closed (no traffic), limited (traffic possible but not in full capacity), open (restriction lifted or not yet in place). The local wording goes in statusLabel; regulationCategory gives the finer public-sector category. When no value fits, leave it out and give the local wording in statusLabel",
"type": "string",
"enum": [
"closed",
"limited",
"open"
],
"x-ngsi": {
"type": "Property"
},
"x-iri": "https://datamodels.jp/ns/transportation/restrictionStatus"
},
"regulationCategory": {
"description": "Regulation category, from the legend of MLIT's Road Information Provision System (道路情報提供システム 通行規制情報, road-info-prvs.mlit.go.jp, accessed 2026-09-24): the categories a road administrator uses for a driver-facing closure or restriction. closedWeather (通行止(異常気象等)) also covers closures after a disaster, such as a landslide or a collapsed road shoulder. Optional and independent of restrictionStatus",
"type": "string",
"enum": [
"closedWeather",
"closedConstruction",
"closedHeavyVehicle",
"closedWinter",
"laneRestriction",
"alternatingOneWay",
"mobileRestriction",
"chainRestriction",
"chainGuidance",
"other"
],
"x-ngsi": {
"type": "Property"
},
"x-iri": "https://datamodels.jp/ns/transportation/regulationCategory"
},
"statusLabel": {
"type": "string",
"minLength": 1,
"description": "The restriction status in the local or source system's wording (依頼中, 通行止め中, 解除済み). Required when restrictionStatus is left out",
"x-ngsi": {
"type": "Property"
},
"x-iri": "https://datamodels.jp/ns/task/statusLabel"
},
"validFrom": {
"description": "When the restriction takes effect",
"type": "string",
"format": "date-time",
"x-ngsi": {
"type": "Property"
},
"x-iri": "https://smartdatamodels.org/validFrom"
},
"validTo": {
"description": "When the restriction is lifted",
"type": "string",
"format": "date-time",
"x-ngsi": {
"type": "Property"
},
"x-iri": "https://smartdatamodels.org/dataModel.Alert/validTo"
},
"description": {
"type": "string",
"description": "Free-text memo",
"x-ngsi": {
"type": "Property"
},
"x-iri": "http://purl.org/dc/terms/description"
},
"patrolRoute": {
"type": "string",
"x-ngsi": {
"type": "Property"
},
"x-iri": "https://example.com/ns/acme/patrolRoute"
}
},
"required": [
"id",
"type",
"location"
],
"anyOf": [
{
"required": [
"restrictionStatus"
]
},
{
"required": [
"statusLabel"
]
}
],
"additionalProperties": false,
"x-extends": "https://datamodels.jp/schema/transportation/RoadRestriction/v1.0.0.json"
}If these attributes belong in the catalog, tell us with the proposal form (filled in for you).
Writing the @context
List the catalog's @context by its URL, then define your attributes next to it. This example adds a patrol route, patrolRoute, to RoadRestriction:
json
{
"@context": [
"https://datamodels.jp/context/transportation/v1.jsonld",
{
"acme": "https://example.com/ns/acme/",
"patrolRoute": "acme:patrolRoute"
}
]
}The catalog's attributes keep their meaning; only yours are new. Name yours under a domain you control (example.com here): the datamodels.jp names belong to the catalog.
Using it in your data
Your data names your @context instead of the catalog's, and has your attributes next to the catalog's:
json
{
"@context": "https://example.com/context/acme-transportation-v1.jsonld",
"id": "urn:ngsi-ld:RoadRestriction:0001",
"type": "RoadRestriction",
"roadName": "靖国通り",
"location": {
"type": "LineString",
"coordinates": [[139.7505, 35.695], [139.752, 35.6956]]
},
"restrictionStatus": "closed",
"patrolRoute": "A-3"
}To send it to an NGSI-LD broker, convert the attributes to the normalized form, and list both your @context and the NGSI-LD core context (The normalized form).
Where to host it
Put your @context at an HTTPS address that you control and that does not change: your own domain, GitHub Pages, or object storage with a fixed address. Brokers and JSON-LD tools fetch it from there.
- Publish each version at its own address, and never change or remove a published file.
- Serve it with
Content-Type: application/ld+jsonandAccess-Control-Allow-Origin: *.
The catalog does not host your @context. You can list your extension on the model page ("Built on by others"), so others who need an attribute with the same meaning can reuse your name: see List your extension.
When the catalog gets new attributes
Your @context takes the catalog's @context by its version alias (v1.jsonld), so new catalog attributes work in your data at once. The JSON Schema does not follow by itself: build it again with the extension builder.
Starting from a Smart Data Models model
It works the same way. Take the upstream @context by an address pinned to a commit, not master (https://raw.githubusercontent.com/smart-data-models/dataModel.<Subject>/<commit>/context.jsonld), so the meaning of your data does not change when upstream changes.
Useful beyond your project?
Propose the attribute to the catalog with the model proposal form. Once it is in the catalog, new data can use the catalog's attribute. Data you already wrote keeps your attribute (and its meaning) until you convert it.