From 5431f2b517d7a8d2ba52a2ad2ff371f83e69e540 Mon Sep 17 00:00:00 2001 From: Jason Fox Date: Mon, 13 Jan 2025 19:13:05 +0100 Subject: [PATCH] Update docs - add VocabProperty, use 1.8 context --- app/README.md | 2 +- docs/concise.md | 94 +++++++++++++++++++++++----------- docs/entity-relationships.md | 18 +++---- docs/extended-properties.md | 32 ++++++------ docs/iot-agent-json.md | 8 +-- docs/iot-agent.md | 8 +-- docs/linked-data.md | 22 ++++---- docs/ngsi-ld-operations.md | 76 +++++++++++++-------------- docs/short-term-history.md | 4 +- docs/understanding-@context.md | 8 +-- docs/working-with-@context.md | 54 ++++++++++++------- 11 files changed, 189 insertions(+), 137 deletions(-) diff --git a/app/README.md b/app/README.md index 7eb0449..98b0c52 100644 --- a/app/README.md +++ b/app/README.md @@ -101,7 +101,7 @@ All Keys and Secrets must be passed in using Environment variables. The followin ## License -MIT © 2020-2023 FIWARE Foundation e.V. +MIT © 2020-2025 FIWARE Foundation e.V. See the LICENSE file in the root of this project for license details. diff --git a/docs/concise.md b/docs/concise.md index a72910b..72abd7c 100644 --- a/docs/concise.md +++ b/docs/concise.md @@ -267,7 +267,10 @@ curl -iX POST 'http://localhost:1026/ngsi-ld/v1/entities/' \ --data-raw '{ "id": "urn:ngsi-ld:TemperatureSensor:001", "type": "TemperatureSensor", - "category": "sensor", + "name": "Sensor 1", + "category": { + "vocab": "sensor" + }, "temperature": { "value": 25, "unitCode": "CEL" @@ -276,7 +279,7 @@ curl -iX POST 'http://localhost:1026/ngsi-ld/v1/entities/' \ ``` New entities can be added by making a POST request to the `/ngsi-ld/v1/entities` endpoint. Notice that because -`category` has no sub-attributes, it does not require a `value` element. +`name` is a Property that has no sub-attributes, it does not require a `value` element. As usual, the request will fail if the entity already exists in the context. @@ -352,7 +355,9 @@ curl -iX POST 'http://localhost:1026/ngsi-ld/v1/entityOperations/create' \ { "id": "urn:ngsi-ld:TemperatureSensor:002", "type": "TemperatureSensor", - "category": ["sensor"], + "category": { + "vocab": ["sensor"] + }, "temperature": { "value": 20, "unitCode": "CEL" @@ -361,7 +366,9 @@ curl -iX POST 'http://localhost:1026/ngsi-ld/v1/entityOperations/create' \ { "id": "urn:ngsi-ld:TemperatureSensor:003", "type": "TemperatureSensor", - "category": ["sensor" , "actuator"], + category": { + "vocab": ["sensor", "actuator"] + }, "temperature": { "value": 2, "unitCode": "CEL" @@ -371,8 +378,8 @@ curl -iX POST 'http://localhost:1026/ngsi-ld/v1/entityOperations/create' \ "id": "urn:ngsi-ld:TemperatureSensor:004", "type": "TemperatureSensor", "category": { - "type": "Property", - "value": "sensor" + "type": "VocabProperty", + "vocab": "sensor" }, "temperature": { "type": "Property", @@ -429,7 +436,9 @@ curl -iX POST 'http://localhost:1026/ngsi-ld/v1/entityOperations/upsert' \ { "id": "urn:ngsi-ld:TemperatureSensor:002", "type": "TemperatureSensor", - "category": "sensor", + category": { + "vocab": "sensor" + }, "temperature": { "value": 21, "unitCode": "CEL" @@ -500,7 +509,7 @@ to content negotiation if the `Accept:application/json` had been set). The full "category": { "createdAt": "2020-08-27T14:33:06Z", "modifiedAt": "2020-08-27T14:33:06Z", - "value": "sensor" + "vocab": "sensor" }, "temperature": { "createdAt": "2020-08-27T14:33:06Z", @@ -579,7 +588,10 @@ The sensor `urn:ngsi-ld:TemperatureSensor:001` is reading at 25°C. The response { "id": "urn:ngsi-ld:TemperatureSensor:001", "type": "TemperatureSensor", - "category": "sensor", + "name": "Sensor 1", + "category": { + "vocab": "sensor" + }, "temperature": { "value": 25, "unitCode": "CEL" @@ -623,7 +635,10 @@ The sensor `urn:ngsi-ld:TemperatureSensor:001` is reading at 25°C. The response { "id": "urn:ngsi-ld:TemperatureSensor:001", "type": "TemperatureSensor", - "category": "sensor", + "name": "Sensor 1", + "category": { + "vocab": "sensor" + }, "temperature": { "value": 25, "unitCode": "CEL" @@ -656,7 +671,9 @@ context will now contain four sensors. { "id": "urn:ngsi-ld:TemperatureSensor:004", "type": "TemperatureSensor", - "category": "sensor", + "category": { + "vocab": "sensor" + }, "temperature": { "value": 100, "unitCode": "CEL" @@ -674,7 +691,9 @@ context will now contain four sensors. { "id": "urn:ngsi-ld:TemperatureSensor:003", "type": "TemperatureSensor", - "category": "sensor", + "category": { + "vocab": "sensor" + }, "temperature": { "type": "Property", "value": 27, @@ -684,6 +703,7 @@ context will now contain four sensors. { "id": "urn:ngsi-ld:TemperatureSensor:001", "type": "TemperatureSensor", + "name": "Sensor 1", "batteryLevel": { "value": 0.8, "unitCode": "C62" @@ -839,8 +859,12 @@ The response details the selected attributes from the selected entities is retur "observedAt": "2022-03-01T15:49:57.039Z", "unitCode": "5K" }, - "phenologicalCondition": "femaleAdult", - "reproductiveCondition": "active", + "phenologicalCondition": { + "vocab": "femaleAdult" + }, + "reproductiveCondition": { + "vocab": "active" + }, "name": "Carnation", "legalID": "M-sow010-Carnation", "sex": "female", @@ -874,8 +898,12 @@ The response details the selected attributes from the selected entities is retur "observedAt": "2022-03-01T15:49:57.287Z", "unitCode": "5K" }, - "phenologicalCondition": "femaleAdult", - "reproductiveCondition": "inCalf", + "phenologicalCondition": { + "vocab": "femaleAdult" + }, + "reproductiveCondition": { + "vocab": "inCalf" + }, "name": "Peach", "legalID": "M-sow006-Peach", "sex": "female", @@ -918,7 +946,7 @@ curl -iX PATCH 'http://localhost:1026/ngsi-ld/v1/entities/urn:ngsi-ld:Temperatur -H 'Content-Type: application/json' \ -H 'Link: ; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"' \ --data-raw '{ - "value": ["sensor", "actuator"] + "vocab": ["sensor", "actuator"] }' ``` @@ -939,7 +967,7 @@ curl -iX PATCH 'http://localhost:1026/ngsi-ld/v1/entities/urn:ngsi-ld:Temperatur -H 'Link: ; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"' \ --data-raw '{ "category": { - "value": [ + "vocab": [ "sensor", "actuator" ] @@ -964,18 +992,22 @@ curl -iX POST 'http://localhost:1026/ngsi-ld/v1/entityOperations/upsert?options= { "id": "urn:ngsi-ld:TemperatureSensor:003", "type": "TemperatureSensor", - "category": [ - "actuator", - "sensor" - ] + "category": { + "vocab": [ + "sensor", + "actuator" + ] + } }, { "id": "urn:ngsi-ld:TemperatureSensor:004", "type": "TemperatureSensor", - "category": [ - "actuator", - "sensor" - ] + "category": { + "vocab": [ + "sensor", + "actuator" + ] + } } ]' ``` @@ -1001,10 +1033,12 @@ curl -iX POST 'http://localhost:1026/ngsi-ld/v1/entityOperations/update?options= { "id": "urn:ngsi-ld:TemperatureSensor:003", "type": "TemperatureSensor", - "category":[ - "actuator", - "sensor" - ] + "category": { + "vocab": [ + "sensor", + "actuator" + ] + } }, { "id": "urn:ngsi-ld:TemperatureSensor:004", diff --git a/docs/entity-relationships.md b/docs/entity-relationships.md index f84ae82..3d51c3b 100644 --- a/docs/entity-relationships.md +++ b/docs/entity-relationships.md @@ -169,7 +169,7 @@ curl -iX POST \ "id": "urn:ngsi-ld:TemperatureSensor:001", "type": "TemperatureSensor", "description" : {"type": "Property", "value": "Temperature Gauge 1"}, - "category": {"type": "Property", "value": "sensor"}, + "category": {"type": "VocabProperty", "vocab": "sensor"}, "controlledProperty" : {"type": "Property", "value": "temperature"}, "temperature": {"type": "Property", "value": 20, "unitCode": "CEL"} }, @@ -177,7 +177,7 @@ curl -iX POST \ "id": "urn:ngsi-ld:TemperatureSensor:002", "type": "TemperatureSensor", "description" : {"type": "Property", "value": "Temperature Gauge 2"}, - "category": {"type": "Property", "value": "sensor"}, + "category": {"type": "VocabProperty", "vocab": "sensor"}, "controlledProperty" : {"type": "Property", "value": "temperature"}, "temperature": {"type": "Property", "value": 21, "unitCode": "CEL"} }, @@ -185,7 +185,7 @@ curl -iX POST \ "id": "urn:ngsi-ld:TemperatureSensor:003", "type": "TemperatureSensor", "description" : {"type": "Property", "value": "Temperature Gauge 3"}, - "category": {"type": "Property", "value": "sensor"}, + "category": {"type": "VocabProperty", "vocab": "sensor"}, "controlledProperty" : {"type": "Property", "value": "temperature"}, "temperature": {"type": "Property", "value": 27, "unitCode": "CEL"} } @@ -206,7 +206,7 @@ curl -iX POST \ "id": "urn:ngsi-ld:FillingLevelSensor:001", "type": "FillingLevelSensor", "description" : {"type": "Property", "value": "Filling Level Sensor 1"}, - "category": {"type": "Property", "value": "sensor"}, + "category": {"type": "VocabProperty", "vocab": "sensor"}, "controlledProperty" : {"type": "Property", "value": "fillingLevel"}, "fillingLevel": {"type": "Property", "value": 1, "unitCode": "C62"} }, @@ -214,7 +214,7 @@ curl -iX POST \ "id": "urn:ngsi-ld:FillingLevelSensor:002", "type": "FillingLevelSensor", "description" : {"type": "Property", "value": "Filling Level Sensor 2"}, - "category": {"type": "Property", "value": "sensor"}, + "category": {"type": "VocabProperty", "vocab": "sensor"}, "controlledProperty" : {"type": "Property", "value": "fillingLevel"}, "fillingLevel": {"type": "Property", "value": 0.9, "unitCode": "C62"} }, @@ -222,7 +222,7 @@ curl -iX POST \ "id": "urn:ngsi-ld:FillingLevelSensor:003", "type": "FillingLevelSensor", "description" : {"type": "Property", "value": "Filling Gauge 3"}, - "category": {"type": "Property", "value": "sensor"}, + "category": {"type": "VocabProperty", "vocab": "sensor"}, "controlledProperty" : {"type": "Property", "value": "fillingLevel"}, "fillingLevel": {"type": "Property", "value": 0.8, "unitCode": "C62"} } @@ -263,7 +263,7 @@ curl -X GET 'http://localhost:1026/ngsi-ld/v1/entities/?type=TemperatureSensor,F "id": "urn:ngsi-ld:TemperatureSensor:001", "type": "TemperatureSensor", "description": "Temperature Gauge 1", - "category": "sensor", + "category": {"vocab": "sensor"}, "controlledProperty": "temperature", "temperature": 20 }, @@ -275,7 +275,7 @@ curl -X GET 'http://localhost:1026/ngsi-ld/v1/entities/?type=TemperatureSensor,F "id": "urn:ngsi-ld:TemperatureSensor:002", "type": "TemperatureSensor", "description": "Temperature Gauge 2", - "category": "sensor", + "category": {"vocab": "sensor"}, "controlledProperty": "temperature", "temperature": 21 }, @@ -384,7 +384,7 @@ The updated response including the `controlledAsset` attribute is shown below: "id": "urn:ngsi-ld:TemperatureSensor:001", "type": "TemperatureSensor", "description": "Temperature Gauge 1", - "category": "sensor", + "category": {"vocab": "sensor"}, "controlledProperty": "temperature", "temperature": 20, "controlledAsset": "urn:ngsi-ld:Building:farm001" diff --git a/docs/extended-properties.md b/docs/extended-properties.md index ed4efc5..d1e017b 100644 --- a/docs/extended-properties.md +++ b/docs/extended-properties.md @@ -77,7 +77,7 @@ this principle, allowing the creation of NGSI-LD properties which directly confo - An NGSI-LD **LanguageProperty** holds a set of internationalized strings and is defined using the JSON-LD `@language` keyword. -- An NGSI-LD **VocabularyProperty** holds is a mapping of a URI to a value within the user'`@context` and is defined +- An NGSI-LD **VocabProperty** holds is a mapping of a URI to a value within the user'`@context` and is defined using the JSON-LD `@vocab` keyword. In each case, the meaning of the resultant payload will be altered according to the standard JSON-LD definitions, so the @@ -289,7 +289,7 @@ strings representing [IETF RFC 5646](https://www.rfc-editor.org/info/rfc5646) la ### Creating a new data entity -This example creates an entity with a **LanguageProperty** and a **VocabularyProperty**. Let's create a farm +This example creates an entity with a **LanguageProperty** and a **VocabProperty**. Let's create a farm **Building** entity in which we want to make the `name` available in three different languages, _English_, _German_, and _Japanese_. The process will be to send a **POST** request to the Broker with the following information: @@ -302,7 +302,7 @@ curl -iX POST 'http://localhost:1026/ngsi-ld/v1/entities/' \ "id": "urn:ngsi-ld:Building:farm001", "type": "Building", "category": { - "type": "VocabularyProperty", + "type": "VocabProperty", "vocab": ["farm"] }, "address": { @@ -350,7 +350,7 @@ Content-Length: 0 #### 2️⃣ Request: -This example creates a second entity with a **LanguageProperty** and a **VocabularyProperty**. Each subsequent entity +This example creates a second entity with a **LanguageProperty** and a **VocabProperty**. Each subsequent entity must have a unique `id` for the given `type`. Note that within a `languageMap`, the `@none` simplified pair indicates the default fallback value to be displayed for unknown languages. @@ -362,7 +362,7 @@ curl -iX POST 'http://localhost:1026/ngsi-ld/v1/entities/' \ "id": "urn:ngsi-ld:Building:barn002", "type": "Building", "category": { - "type": "VocabularyProperty", + "type": "VocabProperty", "vocab": ["barn"] }, "address": { @@ -681,7 +681,7 @@ curl -G -X GET 'http://localhost:1026/ngsi-ld/v1/entities/' \ The User's `@context` is a mechanism for mapping URNs and defining the Entities held within the system It is therefore possible to retrieve _the same data_ using a different set of short names for the attributes, and in the case of a -**VocabularyProperty**, different short names for the values of the attributes themselves. This is particularly useful +**VocabProperty**, different short names for the values of the attributes themselves. This is particularly useful when dealing with distributed data, federations and data spaces as the end user many not have full control of data held within another participant's context broker. @@ -719,7 +719,7 @@ curl -G -X GET 'http://localhost:1026/ngsi-ld/v1/entities/' \ As can be seen, two Building entities are returned with the long names for all the attributes, and in the case of a `vocab` for the attribute value as well. Terms defined in the core context (such as `id`, `type`, `vocab` and -`VocabularyProperty`) are not expanded, as the core context is implied as a default. +`VocabProperty`) are not expanded, as the core context is implied as a default. ```json [ @@ -727,7 +727,7 @@ As can be seen, two Building entities are returned with the long names for all t "id": "urn:ngsi-ld:Building:farm001", "type": "https://uri.fiware.org/ns/dataModels#Building", "https://uri.fiware.org/ns/dataModels#category": { - "type": "VocabularyProperty", + "type": "VocabProperty", "vocab": "https://wiki.openstreetmap.org/wiki/Tag:building%3Dfarm" }, "@context": ["https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld"] @@ -736,7 +736,7 @@ As can be seen, two Building entities are returned with the long names for all t "id": "urn:ngsi-ld:Building:barn002", "type": "https://uri.fiware.org/ns/dataModels#Building", "https://uri.fiware.org/ns/dataModels#category": { - "type": "VocabularyProperty", + "type": "VocabProperty", "vocab": "https://wiki.openstreetmap.org/wiki/Tag:building%3Dbarn" }, "@context": ["https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld"] @@ -747,7 +747,7 @@ As can be seen, two Building entities are returned with the long names for all t #### 1️⃣2️⃣ Request: If the `ngsi-context.jsonld` `@context` is included as a `Link` header in the request, the response will convert all the -attribute names to short names, and in the case of a **VocabularyProperty**, use the short names for the value as well. +attribute names to short names, and in the case of a **VocabProperty**, use the short names for the value as well. ```bash curl -G -X GET 'http://localhost:1026/ngsi-ld/v1/entities/' \ @@ -767,7 +767,7 @@ In the response the categories `farm` and `barn` are used. "id": "urn:ngsi-ld:Building:farm001", "type": "Building", "category": { - "type": "VocabularyProperty", + "type": "VocabProperty", "vocab": "farm" }, "@context": [ @@ -779,7 +779,7 @@ In the response the categories `farm` and `barn` are used. "id": "urn:ngsi-ld:Building:barn002", "type": "Building", "category": { - "type": "VocabularyProperty", + "type": "VocabProperty", "vocab": "barn" }, "@context": [ @@ -810,7 +810,7 @@ The `alternate-context.jsonld` `@context` file maps all the terms and enumeratio #### 1️⃣3️⃣ Request: When `alternate-context.jsonld` included as a `Link` header in the request, the response will convert all the attribute -names to short names used in `alternate-context.jsonld`, and in the case of a **VocabularyProperty**, return the short +names to short names used in `alternate-context.jsonld`, and in the case of a **VocabProperty**, return the short names for the value as well. ```bash @@ -832,7 +832,7 @@ shortname of the Entity `type` has also been amended. "id": "urn:ngsi-ld:Building:farm001", "type": "Gebäude", "kategorie": { - "type": "VocabularyProperty", + "type": "VocabProperty", "vocab": "bauernhof" }, "@context": [ @@ -844,7 +844,7 @@ shortname of the Entity `type` has also been amended. "id": "urn:ngsi-ld:Building:barn002", "type": "Gebäude", "kategorie": { - "type": "VocabularyProperty", + "type": "VocabProperty", "vocab": "scheune" }, "@context": [ @@ -909,7 +909,7 @@ curl -G -X GET 'http://localhost:1026/ngsi-ld/v1/entities/' \ "id": "urn:ngsi-ld:Building:barn002", "type": "Building", "category": { - "type": "VocabularyProperty", + "type": "VocabProperty", "vocab": "barn" }, "@context": [ diff --git a/docs/iot-agent-json.md b/docs/iot-agent-json.md index ec5f757..03a136c 100644 --- a/docs/iot-agent-json.md +++ b/docs/iot-agent-json.md @@ -458,7 +458,7 @@ curl -iX POST 'http://localhost:4041/iot/services' \ ], "static_attributes": [ { - "name": "category", "type": "Property", "value": "sensor" + "name": "category", "type": "VocabProperty", "value": "sensor" }, { "name": "supportedProtocol", "type": "Property", "value": "ul20" @@ -559,7 +559,7 @@ within the **Building** `urn:ngsi-ld:Building:barn001`. > > - _Which **Actuators** currently have a low `batteryLevel`?_ > -> `/ngsi-ld/v1/entities?q=category=="actuator";batteryLevel<0.1` +> `/ngsi-ld/v1/entities?q=category==actuator;batteryLevel<0.1&expandValues=category` > > - _Which **Devices** measuring `fillingLevel` were installed before January 2020?_ > @@ -688,8 +688,8 @@ curl -L -X GET 'http://localhost:1026/ngsi-ld/v1/entities/?type=Device' \ "observedAt": "2020-09-17T09:41:56.755Z" }, "category": { - "type": "Property", - "value": "sensor", + "type": "VocabProperty", + "vocab": "sensor", "observedAt": "2020-09-17T09:41:56.755Z" }, "supportedProtocol": { diff --git a/docs/iot-agent.md b/docs/iot-agent.md index 9b09897..3ee10d7 100644 --- a/docs/iot-agent.md +++ b/docs/iot-agent.md @@ -452,7 +452,7 @@ curl -iX POST 'http://localhost:4041/iot/services' \ ], "static_attributes": [ { - "name": "category", "type": "Property", "value": "sensor" + "name": "category", "type": "VocabProperty", "value": "sensor" }, { "name": "supportedProtocol", "type": "Property", "value": "ul20" @@ -554,7 +554,7 @@ within the **Building** `urn:ngsi-ld:Building:barn001`. > > - _Which **Actuators** currently have a low `batteryLevel`?_ > -> `/ngsi-ld/v1/entities?q=category=="actuator";batteryLevel<0.1` +> `/ngsi-ld/v1/entities?q=category==actuator;batteryLevel<0.1&expandValues=category` > > - _Which **Devices** measuring `fillingLevel` were installed before January 2020?_ > @@ -683,8 +683,8 @@ curl -L -X GET 'http://localhost:1026/ngsi-ld/v1/entities/?type=Device' \ "observedAt": "2020-09-17T09:41:56.755Z" }, "category": { - "type": "Property", - "value": "sensor", + "type": "VocabProperty", + "vocab": "sensor", "observedAt": "2020-09-17T09:41:56.755Z" }, "supportedProtocol": { diff --git a/docs/linked-data.md b/docs/linked-data.md index 1ecd6d9..4194be2 100644 --- a/docs/linked-data.md +++ b/docs/linked-data.md @@ -73,7 +73,7 @@ Within the **NGSI-LD** Smart Farm, all of the Building Entities are marked using which can be expanded to a full URI `https://uri.fiware.org/ns/dataModels#Building` using JSON-LD expansion rules. All the attributes of each Building entity (such as `name`, `category` etc are defined using the [User `@context`](./data-models/ngsi-context.jsonld) and are structured as NGSI-LD attributes. The standard NGSI-LD -Keywords are used to define the nature of each attribute - e.g. `Property`, `GeoProperty`, `VocabularyProperty`, +Keywords are used to define the nature of each attribute - e.g. `Property`, `GeoProperty`, `VocabProperty`, `Relationship` and each of these terms is also defined within the [core `@context`](https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld). @@ -82,7 +82,7 @@ Keywords are used to define the nature of each attribute - e.g. `Property`, `Geo "id": "urn:ngsi-ld:Building:farm001", "type": "Building", "category": { - "type": "VocabularyProperty", + "type": "VocabProperty", "vocab": "farm" }, "address": { @@ -118,7 +118,7 @@ Within the **NGSI-v2** Smart Supermarket, every entity must have a `id` and `typ a prerequisite for joining the data space. However due to the backend systems used, the internal short name is `"type":"Store"`. Within an **NGSI-v2** system there is no concept of `@context` - every attribute has a `type` and a `value` and the attribute `type` is usually aligned with the datatype (e.g. `Text`, `PostalAddress`) although since -**NGSI-LD** keyword types such as `Relationship`, `VocabularyProperty` are also permissible and set by convention. +**NGSI-LD** keyword types such as `Relationship`, `VocabProperty` are also permissible and set by convention. ```json { @@ -134,7 +134,7 @@ a prerequisite for joining the data space. However due to the backend systems us } }, "category": { - "type": "VocabularyProperty", + "type": "VocabProperty", "value": "supermarket" }, "location": { @@ -329,7 +329,7 @@ The response will be in NGSI-v2 format as follows: }, "metadata": {} }, "category": { - "type": "VocabularyProperty", "value": "supermarket", "metadata": {} + "type": "VocabProperty", "value": "supermarket", "metadata": {} }, "location": { "type": "geo:json", @@ -348,14 +348,14 @@ The response will be in NGSI-v2 format as follows: "type": "Relationship", "value": "urn:ngsi-ld:Person:001", "metadata": { "objectType": { - "type": "VocabularyProperty", "value": "Person" + "type": "VocabProperty", "value": "Person" } } } } ``` -The `type` attribute in NGSI-v2 is loosely defined, but in this case, with the exception of ordinary properties, we are using `type` to correspond to the terms used in NGSI-LD such as `Relationship` or `VocabularyProperty`. For ordinary NGSI-v2 properties, the `type` corresponds to a datatype such as `Text` or `PostalAddress`, each of these datatypes will need to be mapped to a JSON-LD `@context` if the data is to be understood in an NGSI-LD system. +The `type` attribute in NGSI-v2 is loosely defined, but in this case, with the exception of ordinary properties, we are using `type` to correspond to the terms used in NGSI-LD such as `Relationship` or `VocabProperty`. For ordinary NGSI-v2 properties, the `type` corresponds to a datatype such as `Text` or `PostalAddress`, each of these datatypes will need to be mapped to a JSON-LD `@context` if the data is to be understood in an NGSI-LD system. ### Reading NGSI-v2 Data in NGSI-LD format @@ -393,7 +393,7 @@ The response will be in NGSI-LD format as follows: } }, "category": { - "type": "VocabularyProperty", "vocab": "supermarket" + "type": "VocabProperty", "vocab": "supermarket" }, "location": { "type": "GeoProperty", @@ -414,7 +414,7 @@ The response will be in NGSI-LD format as follows: } ``` -It should be noted that the `@context` supplied in the `Link` header has been totally ignored, and a fixed `@context` used configured for the adaptor has been returned instead. The Adaptor doesn't fully understand NGSI-LD, it merely formats the underlying NGSI-v2 as NGSI-LD. You will notice that the NGSI-v2 `"type": "VocabularyProperty", "value": "supermarket"` has been amended to a valid **VocabularyProperty** - `"type": "VocabularyProperty", "vocab": "supermarket"`, and similarly the **Relationship** is now using `object` and `objectType` as defined in the core `@context` +It should be noted that the `@context` supplied in the `Link` header has been totally ignored, and a fixed `@context` used configured for the adaptor has been returned instead. The Adaptor doesn't fully understand NGSI-LD, it merely formats the underlying NGSI-v2 as NGSI-LD. You will notice that the NGSI-v2 `"type": "VocabProperty", "value": "supermarket"` has been amended to a valid **VocabProperty** - `"type": "VocabProperty", "vocab": "supermarket"`, and similarly the **Relationship** is now using `object` and `objectType` as defined in the core `@context` @@ -546,7 +546,7 @@ curl -L 'http://localhost:1026/ngsi-ld/v1/entities/urn:ngsi-ld:Store:001' \ #### Response: -Because of `Prefer: ngsi-ld=1.6` had been set in the registration, the retrieved entity does not a **VocabularyProperty** and `objectType` has been quietly dropped from the response. This ensures backwards compatibility to context brokers conformant to an earlier version of the NGSI-LD specification - in this case version 1.6. +Because of `Prefer: ngsi-ld=1.6` had been set in the registration, the retrieved entity does not a **VocabProperty** and `objectType` has been quietly dropped from the response. This ensures backwards compatibility to context brokers conformant to an earlier version of the NGSI-LD specification - in this case version 1.6. ```json { @@ -561,7 +561,7 @@ Because of `Prefer: ngsi-ld=1.6` had been set in the registration, the retrieved "postalCode": "10439" } }, - "category": {"type": "Property", "value": "supermarket"}, + "category": {"type": "VocabProperty", "vocab": "supermarket"}, "location": { "type": "GeoProperty", "value": { diff --git a/docs/ngsi-ld-operations.md b/docs/ngsi-ld-operations.md index 3305d7e..b04e3ed 100644 --- a/docs/ngsi-ld-operations.md +++ b/docs/ngsi-ld-operations.md @@ -202,8 +202,8 @@ curl -iX POST 'http://localhost:1026/ngsi-ld/v1/entities/' \ "id": "urn:ngsi-ld:TemperatureSensor:001", "type": "TemperatureSensor", "category": { - "type": "Property", - "value": "sensor" + "type": "VocabProperty", + "vocab": "sensor" }, "temperature": { "type": "Property", @@ -291,8 +291,8 @@ curl -iX POST 'http://localhost:1026/ngsi-ld/v1/entityOperations/create' \ "id": "urn:ngsi-ld:TemperatureSensor:002", "type": "TemperatureSensor", "category": { - "type": "Property", - "value": "sensor" + "type": "VocabProperty", + "vocab": "sensor" }, "temperature": { "type": "Property", @@ -304,8 +304,8 @@ curl -iX POST 'http://localhost:1026/ngsi-ld/v1/entityOperations/create' \ "id": "urn:ngsi-ld:TemperatureSensor:003", "type": "TemperatureSensor", "category": { - "type": "Property", - "value": "sensor" + "type": "VocabProperty", + "vocab": "sensor" }, "temperature": { "type": "Property", @@ -317,8 +317,8 @@ curl -iX POST 'http://localhost:1026/ngsi-ld/v1/entityOperations/create' \ "id": "urn:ngsi-ld:TemperatureSensor:004", "type": "TemperatureSensor", "category": { - "type": "Property", - "value": "sensor" + "type": "VocabProperty", + "vocab": "sensor" }, "temperature": { "type": "Property", @@ -367,8 +367,8 @@ curl -iX POST 'http://localhost:1026/ngsi-ld/v1/entityOperations/upsert' \ "id": "urn:ngsi-ld:TemperatureSensor:002", "type": "TemperatureSensor", "category": { - "type": "Property", - "value": "sensor" + "type": "VocabProperty", + "vocab": "sensor" }, "temperature": { "type": "Property", @@ -380,8 +380,8 @@ curl -iX POST 'http://localhost:1026/ngsi-ld/v1/entityOperations/upsert' \ "id": "urn:ngsi-ld:TemperatureSensor:003", "type": "TemperatureSensor", "category": { - "type": "Property", - "value": "sensor" + "type": "VocabProperty", + "vocab": "sensor" }, "temperature": { "type": "Property", @@ -445,10 +445,10 @@ moved due to content negotiation if the `Accept:application/json` had been set). "createdAt": "2020-08-27T14:33:06Z", "modifiedAt": "2020-08-27T14:33:10Z", "category": { - "type": "Property", + "type": "VocabProperty", "createdAt": "2020-08-27T14:33:06Z", "modifiedAt": "2020-08-27T14:33:06Z", - "value": "sensor" + "vocab": "sensor" }, "temperature": { "type": "Property", @@ -604,8 +604,8 @@ context will now contain four sensors. "id": "urn:ngsi-ld:TemperatureSensor:004", "type": "TemperatureSensor", "category": { - "type": "Property", - "value": "sensor" + "type": "VocabProperty", + "vocab": "sensor" }, "temperature": { "type": "Property", @@ -621,8 +621,8 @@ context will now contain four sensors. "id": "urn:ngsi-ld:TemperatureSensor:002", "type": "TemperatureSensor", "category": { - "type": "Property", - "value": "sensor" + "type": "VocabProperty", + "vocab": "sensor" }, "temperature": { "type": "Property", @@ -638,8 +638,8 @@ context will now contain four sensors. "id": "urn:ngsi-ld:TemperatureSensor:003", "type": "TemperatureSensor", "category": { - "type": "Property", - "value": "sensor" + "type": "VocabProperty", + "vocab": "sensor" }, "temperature": { "type": "Property", @@ -660,8 +660,8 @@ context will now contain four sensors. "unitCode": "C62" }, "category": { - "type": "Property", - "value": "sensor" + "type": "VocabProperty", + "vocab": "sensor" }, "controlledAsset": { "type": "Relationship", @@ -777,8 +777,8 @@ curl -iX PATCH 'http://localhost:1026/ngsi-ld/v1/entities/urn:ngsi-ld:Temperatur -H 'Content-Type: application/json' \ -H 'Link: ; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"' \ --data-raw '{ - "value": ["sensor", "actuator"], - "type": "Property" + "vocab": ["sensor", "actuator"], + "type": "VocabProperty" }' ``` @@ -799,11 +799,11 @@ curl -iX PATCH 'http://localhost:1026/ngsi-ld/v1/entities/urn:ngsi-ld:Temperatur -H 'Link: ; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"' \ --data-raw '{ "category": { - "value": [ + "vocab": [ "sensor", "actuator" ], - "type": "Property" + "type": "VocabProperty" }, "controlledAsset": { "type": "Relationship", @@ -827,8 +827,8 @@ curl -iX POST 'http://localhost:1026/ngsi-ld/v1/entityOperations/upsert?options= "id": "urn:ngsi-ld:TemperatureSensor:003", "type": "TemperatureSensor", "category": { - "type": "Property", - "value": [ + "type": "VocabProperty", + "vocab": [ "actuator", "sensor" ] @@ -838,8 +838,8 @@ curl -iX POST 'http://localhost:1026/ngsi-ld/v1/entityOperations/upsert?options= "id": "urn:ngsi-ld:TemperatureSensor:004", "type": "TemperatureSensor", "category": { - "type": "Property", - "value": [ + "type": "VocabProperty", + "vocab": [ "actuator", "sensor" ] @@ -870,8 +870,8 @@ curl -iX POST 'http://localhost:1026/ngsi-ld/v1/entityOperations/update?options= "id": "urn:ngsi-ld:TemperatureSensor:003", "type": "TemperatureSensor", "category": { - "type": "Property", - "value": [ + "type": "VocabProperty", + "vocab": [ "actuator", "sensor" ] @@ -881,8 +881,8 @@ curl -iX POST 'http://localhost:1026/ngsi-ld/v1/entityOperations/update?options= "id": "urn:ngsi-ld:TemperatureSensor:004", "type": "TemperatureSensor", "temperature": { - "type": "Property", - "value": [ + "type": "VocabProperty", + "vocab": [ "actuator", "sensor" ] @@ -978,17 +978,17 @@ curl -L -X PATCH 'http://localhost:1026/ngsi-ld/v1/entities/urn:ngsi-ld:Temperat -H 'Link: ; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"' \ --data-raw '{ "category": { - "value": null, - "type": "Property" + "vocab": "urn:ngsi-ld:null", + "type": "VocabProperty" }, "controlledAsset": { "type": "Relationship", - "object": null + "object": "urn:ngsi-ld:null" } }' ``` -If a value is set to `null` the attribute is deleted. +If a value is set to `urn:ngsi-ld:null` the attribute is deleted. ### Find existing data relationships diff --git a/docs/short-term-history.md b/docs/short-term-history.md index 274115d..0af72c7 100644 --- a/docs/short-term-history.md +++ b/docs/short-term-history.md @@ -948,8 +948,8 @@ attribute has also been added to the model: "observedAt": "2021-09-16T15:24:15.781Z" }, "category": { - "value": "sensor", - "type": "Property", + "vocab": "sensor", + "type": "VocabProperty", "observedAt": "2021-09-16T15:24:15.781Z" }, "controlledProperty": { diff --git a/docs/understanding-@context.md b/docs/understanding-@context.md index b22f276..145fbb2 100644 --- a/docs/understanding-@context.md +++ b/docs/understanding-@context.md @@ -473,7 +473,7 @@ applications. The file is structured into three parts: - A list of attributes (e.g. `address`) and enumerations (e.g. `barn`) Effectively this NGSI-LD `@context` can be combined with a copy of the NGSI-LD core context -[https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context.jsonld](https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context.jsonld) +[https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld](https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld) to mechanically define the following: If a computer encounters an entity of `type=Building` this really refers to a @@ -498,8 +498,8 @@ For example this is a `Building` in _normalized_ NGSI-LD format: "id": "urn:ngsi-ld:Building:001", "type": "Building", "category": { - "type": "Property", - "value": "barn" + "type": "VocabProperty", + "vocab": "barn" }, "address": { "type": "Property", @@ -523,7 +523,7 @@ For example this is a `Building` in _normalized_ NGSI-LD format: }, "@context": [ "https://example.com/data-models.context-ngsild.jsonld", - "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context.jsonld" + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" ] } ``` diff --git a/docs/working-with-@context.md b/docs/working-with-@context.md index 7bd2b75..2dad988 100644 --- a/docs/working-with-@context.md +++ b/docs/working-with-@context.md @@ -329,8 +329,8 @@ curl -iX POST 'http://localhost:1026/ngsi-ld/v1/entities/' \ "id": "urn:ngsi-ld:Building:farm001", "type": "Building", "category": { - "type": "Property", - "value": ["farm"] + "type": "VocabProperty", + "vocab": ["farm"] }, "address": { "type": "Property", @@ -394,8 +394,8 @@ curl -iX POST 'http://localhost:1026/ngsi-ld/v1/entities/' \ "id": "urn:ngsi-ld:Building:barn002", "type": "Building", "category": { - "type": "Property", - "value": ["barn"] + "type": "VocabProperty", + "vocab": ["barn"] }, "address": { "type": "Property", @@ -522,8 +522,8 @@ be displayed. "value": "Victory Farm" }, "https://uri.fiware.org/ns/dataModels#category": { - "type": "Property", - "value": "farm" + "type": "VocabProperty", + "vocab": "https://wiki.openstreetmap.org/wiki/Tag:building%3Dfarm" }, "location": { "type": "GeoProperty", @@ -555,8 +555,8 @@ be displayed. "value": "Big Red Barn" }, "https://uri.fiware.org/ns/dataModels#category": { - "type": "Property", - "value": "barn" + "type": "VocabProperty", + "vocab": "https://wiki.openstreetmap.org/wiki/Tag:building%3Dbarn" }, "location": { "type": "GeoProperty", @@ -610,7 +610,7 @@ files explicitly as element in the array of `@context` sent. The response is nor "id": "urn:ngsi-ld:Building:farm001", "type": "Building", "category": { - "type": "Property", + "type": "VocabProperty", "value": "farm" }, "address": { @@ -683,7 +683,9 @@ used as the `@context` returned to the response. "postalCode": "10557" }, "name": "Victory Farm", - "category": "farm", + "category": { + "vocab": "farm" + }, "location": { "type": "Point", "coordinates": [13.3505, 52.5144] @@ -703,7 +705,9 @@ used as the `@context` returned to the response. "postalCode": "10557" }, "name": "Big Red Barn", - "category": "barn", + "category": { + "vocab":"barn" + }, "location": { "type": "Point", "coordinates": [13.3698, 52.5163] @@ -751,7 +755,9 @@ The use of the `Link` header and the `options=keyValues` parameter reduces the r "postalCode": "10557" }, "name": "Big Red Barn", - "category": "barn", + "category": { + "vocab": "barn" + }, "location": { "type": "Point", "coordinates": [13.3698, 52.5163] @@ -871,7 +877,9 @@ The response is returned in JSON-LD format with short form attribute names: "postalCode": "10557" }, "name": "Big Red Barn", - "category": "barn", + "category": { + "vocab": "barn" + }, "location": { "type": "Point", "coordinates": [13.3698, 52.5163] @@ -918,7 +926,9 @@ Use of the `Link` header and the `options=keyValues` parameter reduces the respo "postalCode": "10557" }, "name": "Victory Farm", - "category": "farm", + "category": { + "vocab": "farm" + }, "location": { "type": "Point", "coordinates": [13.3505, 52.5144] @@ -938,7 +948,9 @@ Use of the `Link` header and the `options=keyValues` parameter reduces the respo "postalCode": "10557" }, "name": "Big Red Barn", - "category": "barn", + "category": { + "vocab": "barn" + }, "location": { "type": "Point", "coordinates": [13.3698, 52.5163] @@ -983,7 +995,9 @@ consists of JSON only without the attribute `type` and `metadata` elements. "postalCode": "10557" }, "name": "Victory Farm", - "category": "farm", + "category": { + "vocab": "farm" + }, "location": { "type": "Point", "coordinates": [13.3505, 52.5144] @@ -999,7 +1013,9 @@ consists of JSON only without the attribute `type` and `metadata` elements. "postalCode": "10557" }, "name": "Big Red Barn", - "category": "barn", + "category": { + "vocab": "barn" + }, "location": { "type": "Point", "coordinates": [13.3698, 52.5163] @@ -1052,7 +1068,9 @@ consists of JSON only without the attribute `type` and `metadata` elements. "postalCode": "10557" }, "name": "Big Red Barn", - "category": "barn", + "category": { + "vocab": "barn" + }, "location": { "type": "Point", "coordinates": [13.3698, 52.5163]