Merge branch 'SDS-2024-0118R01-Value_provided_by_NGSI-LD_Use_Cases' into 'R5'

SDS-2024-0118R01-Value provided by NGSI-LD use cases

See merge request specifications/tr-0076!5

TR-0076-Integrating_NGSI-LD_API_in_oneM2M.md

@@ -442,7 +442,335 @@ As mentioned above, the underlying distribution is largely transparent to the Co
 
 # 6 Assessment of additional functionality brought by NGSI-LD
 
-<mark>Based on the introduction in clause 5, description of the additional functionality that the integration of NGSI-LD API and its related functionality can bring to the oneM2M standard, including the resulting integrated use cases. </mark>
+## 6.1 Introduction
+
+Based on the general introduction of NGSI-LD in clause 5, clause 6 describes which advantages the integration of the NGSI-LD API into the oneM2M standard can bring to oneM2M applications. For this purpose, a number of use cases are analysed, highlighting the respective advantages for applications. Finally, the advantages are summarized with the goal of providing directions for further explorations of how the integration of NGSI-LD into oneM2M can be achieved, which is the focus of the following clauses.
+
+## 6.2 Use Case: Query parking sites in the vicinity (UC1)
+
+Use Case 1 (UC1) is about querying for parking sites within a given geographic area, e.g. around the current location of a car.
+Figure 6.2-1 visualizes this scenario.
+
+![UC1 - Query parking sites in the vicinity](media/UC1-query_parking_sites-visualization.png)
+
+**Figure 6.2-1: UC1 - Query parking sites in the vicinity**
+
+The basis for modelling the information required for this use case is the NGSI-LD compatible Smart Data Model<a href="#_ref_i.5">[i.5]</a> on Parking, which makes a distinction between OffStreetParking and OnStreetParking. As this distinction is not relevant for our use case, we restrict the example on a number of common NGSI-LD properties:
+- address
+- allowedVehicleType
+- availableSpotNumber
+- category
+- chargeType
+- location
+
+The query for parking sites within a given geographic area, e.g. around the current location of a car: 
+```
+GET /ngsi-ld/v1/entities/?type=OnStreetParking,OffStreetParking&geoproperty=location&georel=near%3BmaxDistance==1000&geometry=Point&coordinates[-3.8040616,43.4631649]
+
+Accept: application/json
+Host: localhost:9090
+Link: <http://example.org/myContext.jsonld>; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"
+
+```
+It queries for all NGSI-LD Entities of type OnStreetParking or OffStreetParking, and geographically scopes it with the circle around the geographic point with coordinates -3.8040616,43.4631649 and a radius of 1000m.
+
+
+Excerpt of result:
+```
+[{
+    "id": "urn:ngsi-ld:OnStreetParking:santander:daoiz_velarde_1_5",
+    "type": "OnStreetParking",
+    "allowedVehicleType": {
+        "type": "Property",
+        "value": [
+            "car"
+        ]
+    },
+	"availableSpotNumber": {
+        "type": "Property",
+        "value": 3,
+        "observedAt": "2018-09-12T12:00:00Z"
+    },
+    "category": {
+        "type": "Property",
+        "value": [
+            "blueZone",
+            "shortTerm",
+            "forDisabled"
+        ]
+    },
+    "chargeType": {
+        "type": "Property",
+        "value": [
+            "temporaryFee"
+        ]
+	...
+```
+
+The advantages for the application are the following:
+- Application can reuqest information by specifying what it needs ("parking sites in the vicinity")
+- Application gets result with a single request (unless paging is required due to number of results)
+- Application can gegographically scope the request
+
+In order to do this, the application needs to know the following:
+- Data model:
+  - type: OnStreetParking, OffStreetParking
+  - GeoProperty name: location
+- its current location
+- Root URL: localhost:9090
+
+## 6.3 Use Case: Query parking sites in the vicinity (UC2)
+
+Use Case 2 (UC2) is about querying for a _free_ parking spot within the proximity of a car. 
+Figure 6.3-1 visualizes this scenario.
+
+![UC2 - Query for free parking spots in proximity](media/UC2-query_free_parking_spot-visualization.png)
+
+**Figure 6.3-1: UC2 - Query for free parking spots in the proximity**
+
+The NGSI-LD Entity Type used is ParkingSpot, also from the NGSI-LD compatible Smart Data Model<a href="#_ref_i.5">[i.5]</a> on Parking. For this purpose, we are only interested in the following properties of each parking spot:
+- categrory
+- location
+- name
+- parkingSite (relation)
+- status
+
+The query for parking spots within a given geographic area, e.g. within 100m around the current location of a car, filtered according to the status being _free_ and restricting the result to the elments: id, type, category, location, name and status: 
+```
+GET /ngsi-ld/v1/entities/?type=ParkingSpot&geoproperty=location&georel=near%3BmaxDistance==100&geometry=Point&coordinates=[-3.8040616,43.4631649]&q=status==“free”&pick=id,type,category,location,name,status
+
+Accept: application/json
+Host: localhost:9090
+Link: <http://example.org/myContext.jsonld>; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"
+
+```
+Excerpt of result:
+```
+[{
+    "id": "urn:ngsi-ld:ParkingSpot:santander:daoiz_velarde_1_5:3",
+    "type": "ParkingSpot",
+    "category": {
+        "type": "Property",
+        "value": [
+            "onStreet"
+        ]
+    },
+    "location": {
+        "type": "GeoProperty",
+        "value": {
+            "type": "Point",
+            "coordinates": [
+                -3.80356167695194,
+                43.46296641666926
+            ]
+        }
+    },
+    "name": {
+        "type": "Property",
+        "value": "A-13"
+     "status": {
+        "type": "Property",
+        "value": "free",
+        "observedAt": "2018-09-21T12:00:00Z“
+     }
+}, 
+...
+```
+
+The advantages for the application are the following:
+- Application can reuqest information by specifying what it needs ("free parking spaces in the close vicinity")
+- Application gets result with a single request (unless paging is required due to number of results)
+- Application can gegographically scope the request
+- Application can filter by status, i.e. only get “free” parking spaces
+- Application can project to only get the properties and relationships they are interested in
+
+
+In order to do this, the application needs to know the following:
+- Data model:
+  - type: ParkingSpot
+  - GeoProperty name: location
+  - Property names: category, location, name and status – and its possible values (“free”)
+- its current location
+- Root URL: localhost:9090
+
+## 6.4 Use Case: Retrieve or query agriculture parcel(s) modelled as composite digital twins (UC3)
+
+Use Case 3 (UC3) is retrieving (or querying for) agriculture parcel(s) modelled as composite digital twins.
+Figure 6.4-1 visualizes this scenario.
+
+![UC3 - Retrieve agricultural parcel](media/UC3-retrieve_agricultural_parcel_modelled_as_digital_twin.png)
+
+**Figure 6.4-1: UC3 - Retrieve agricultural parcel**
+
+The NGSI-LD Entity Type used is AgriParcel, also from the NGSI-LD compatible Smart Data Model<a href="#_ref_i.5">[i.5]</a> on Agrifood. For this purpose, we are interested in the following properties and relationships of AgriParcel:
+- soil type
+- crop type
+- location
+- prediction (relationship to Weather Forecast)
+- observation (relationship to Weather Station)
+
+Entities of type WeatherStation have at least the following properties:
+- temperature
+- humidity
+
+Entities of type WeatherForecast have at least the following properties:
+- temperature
+- humidity
+- wind speed
+
+The retrieve operation for a specific AgriParcel (AgriParcel:001) looks as follows:
+```
+GET /ngsi-ld/v1/entities/urn:ngsi-ld:AgriParcel:001? format=concise&join=inline&joinLevel=1
+Accept: application/json
+Host: localhost:9090
+Link: <http://example.org/myContext.jsonld>; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"
+
+```
+Introducing a _join_ and _joinLevel_ allows following the relationships and integrating the entities pointed to by the relation into the result, creating a hierarchy of entities.
+
+Excerpt of result:
+```
+{
+  "id": "urn:ngsi-ld:AgriParcel:001",
+  "type": “AgriParcel",
+  "soilType": "Loamy",
+  "prediction": {
+	"object": "urn:ngsi-ld:WeatherForecast:XXX",
+	"objectType": “WeatherForecast", 
+	"entity": {
+	    "id": "urn:ngsi-ld:WeatherForecast:XXX ",
+	    "type": “WeatherForecast",
+		"humidity": {"value": 98, "unitCode: "PCT"},
+	  	"temperature": {"value": 30, "unitCode: "CEL"},
+	  	"windSpeed": {"value": 3, "unitCode: "MPH"}
+  }},
+  “observation": {
+	"object": "urn:ngsi-ld:WeatherObserved:001",
+	"objectType": “WeatherObserved",
+	"entity": {
+		"id": "urn:ngsi-ld:WeatherObserved:001",
+		"type": “WeatherObserved",
+	...
+}
+```
+
+If the specific AgriParcel is not a-priori known, a query for NGSI-LD Entities of type AgriParcel with a geographic scope can be used as in UC1 and UC2.
+
+```
+GET /ngsi-ld/v1/entities/?type=AgriParcel&geoproperty=location&georel=near%3BmaxDistance==1000&geometry=Point&coordinates=[57.5522023,-20.34840123]&format=concise&join=inline&joinLevel=1
+Accept: application/json
+Host: localhost:9090
+Link: <http://example.org/myContext.jsonld>; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"
+
+```
+
+The advantages for the application are the following:
+- Application can request information by specifying what it needs (“information about parcel(s) of land together with respective weather info”)
+- Application gets results with a single request (unless paging is required due to number of results)
+- Application can geographically scope the request (for the query)
+- Application can request that relationships are followed, and the related entities are embedded (up to a given depth) in the result
+
+In order to do this, the application needs to know the following:
+- Data model:
+  - type: AgriParcel
+  - Relationships (worth following): observation, prediction
+  - GeoProperty name: location
+- Root URL: localhost:9090
+
+## 6.5 Use Case: Subscribe to be notified when temperature is above/below threshold in building (UC4)
+
+Use Case 4 (UC4) is subscribing to changes in the indoor temperature of a building, filtering for an indoor temperature greater than 30°C, i.e. only once the threshold of 30°C has been crossed, notifications are going to be sent. Figure 6.5-1 visualizes this scenario.
+
+![UC4 - Subscribe to be notified whenever temperature changes and is above threshold](media/UC4-subscribe_to_be_notified_when_temperature_is_above_or_below_threshold.png)
+
+**Figure 6.5-1: UC4 - Subscribe to be notified whenever temperature changes and is above threshold**
+
+The NGSI-LD Entity Type used is Building, also from the NGSI-LD compatible Smart Data Model<a href="#_ref_i.5">[i.5]</a> on Smart Cities. For this purpose, we are interested in the following properties of Building:
+- category
+- floorsAboveGround
+- floorsBelowGround
+- indoorTemperature
+- location
+- owner
+
+The subscribe operation for the _indoor temperature_ of the _Building_ with the _id_ "building-a85e3da145c1" and the filter on _indoorTemperature_ greater that _30_ looks as follows:
+```
+{
+    "id": "urn:ngsi-ld:Subscription:storeSubscription4",
+    "type": "Subscription",
+    "entities": [
+        {
+            "id": "urn:ngsi-ld:Building:building-a85e3da145c1",
+            "type": "Building"
+        }
+    ],
+    "watchedAttributes": ["indoorTemperature"],
+	"q": "indoorTemperature>30",
+    "notification": {
+        "format": "normalized",
+        "endpoint": {
+            "uri": "http://localhost:8080",
+            "accept": "application/json"
+        }
+    }
+}
+```
+Excerpt of resulting notification:
+```
+{
+    "id": "urn:ngsi-ld:Notification:515236543545",
+    "type": "Notification",
+    "subscriptionId": "urn:ngsi-ld:Subscription:storeSubscription4",	
+    "data": {
+	  "id": "urn:ngsi-ld:Building:building-a85e3da145c1",
+	  "type": "Building",
+	  "address": {
+	    "type": "Property",
+	    "value": {
+	      "addressLocality": "London",
+	      "postalCode": "EC4N 8AF",
+	      "streetAddress": "25 Walbrook"
+	    }
+	  },
+	  "category": {
+	    "type": "Property",
+	    "value": [
+	      "office"
+	    ]
+	  },
+	  “indoorTemperature": {
+	    "type": "Property",
+	    "value": 31.3,
+	  }
+	  ...
+	}
+}
+```
+The advantages for the application are the following:
+- Application can subscribe to be notified whenever the specified information changes(“indoor temperature of a building”)
+- Application gets notification on change
+- Application can request to only be notified in case a value is above a certain threshold (indoorTemperature>30)
+
+In order to do this, the application needs to know the following:
+- Data model:
+  - type: Building
+  - Property: indoorTemperature (and its value, e.g. that Celsius scale is used)
+- Root URL: localhost:9090
+
+## 6.6 Summary of advantageous NGSI-LD functionalities
+
+The following bullet points provide a summary of the NGSI-LD functionalities that are advantageous for certain applications as identified in the use cases presented above.
+
+- Applications can request information by specifying what they need. This is especially important for applications that on the one hand want to (re-)use information, but on the other hand do not want to deal with 
+  - first finding out where information is stored in the system
+  - understanding different resource structures
+  - handling various native data representations
+- Applications can geographically scope queries
+- Applications can filter results based on property values / relationship targets
+- Application can project to only get the properties and relationships they are interested in
+- Applications can get back whole entity graphs by following relationships. This can be especially relevant for (composite) Digital Twins
+- With queries, applications can get back result with a single request, i.e. there is no separate discovery step followed by retrieval(s).
+- Applications can subscribe to be notified of relevant changes in information (or periodically, for which no example has been shown)
 
 # 7 Architectural integration of NGSI-LD into oneM2M