Contribution SDS-2024-0142R02-Mapping_Approach-oneM2M_Information_via_NGSI-LD merged into R5

Original contribution: SDS-2024-0142-Mapping_Approach-oneM2M_Information_via_NGSI-LD

See merge request !7

TR-0076-Integrating_NGSI-LD_API_in_oneM2M.md

@@ -774,7 +774,44 @@ The following bullet points provide a summary of the NGSI-LD functionalities tha
 
 # 7 Architectural integration of NGSI-LD into oneM2M
 
-<mark>Study solutions for the  architectural integration of NGSI-LD and its related functionalities into oneM2M, in particular with respect to oneM2M reference points and the existing oneM2M Common Service Functions.</mark>
+## 7.1 Introduction
+Clause 7 studies solutions for the  architectural integration of NGSI-LD and its related functionalities into oneM2M, in particular with respect to oneM2M reference points and the existing oneM2M Common Service Functions.
+
+## 7.2 Mapping Approach - Making oneM2M Information available via NGSI-LD
+
+### 7.2.1 Motivation
+
+oneM2M resource structures already contain relevant information, however, applications often have to first discover and then individually retrieve this information to check whether it is actually relevant for them. The goal of this approach is to make the information stored in existing oneM2M resources also available to applications via the NGSI-LD API, enabling application to specify and efficiently retrieve the information they actually need.
+
+In particular, applications can request the information by specifying the following:
+- Applications can filter and scope based on the information itself (as opposed to meta information attached to resources). Specific index structures can be used to make access efficient due to the common meta information model.
+- Application can project to only get the properties and relationships they are interested in (as opposed to getting the content on resource granularity)
+- Applications can get back whole entity graphs by following relationships (e.g. across multiple resources)
+
+Applications have the following interaction options using NGSI-LD:
+- Retrieve specific information they can already identify, i.e. as an NGSI-LD Entity with a given identifier
+- Query relevant information as described above and getting back all results, in form of NGSI-LD Entities, with a single request. There is no separate discovery step followed by retrieval(s).
+- Subscribe to be notified of relevant changes in information, or periodically.
+
+### 7.2.2 Sketch of Mapping Approach
+
+The idea of the approach is to define a general mechanism based on a mapping language. With this approach, users can define a mapping, e.g., how a value that can be extracted from a oneM2M resource is the value of an NGSI-LD property, belonging to a specifc NGSI-LD Entity with a certain NGSI-LD type. These user-provided mappings could be stored in \<semanticDescriptor\> resources. Alternatively, a specific mapping resource type could be defined.
+
+Figure 7.2-1 shows two oneM2M resource structures, e.g. two \<container\> resources with \<contentInstance\> resources and one \<semanticDescriptor\> resource each. The \<contentInstance\> resources encapsulate information as provided by the source, e.g. a device or IPE. The <semanticDescriptor> resources contain the mapping that describes how the value can be extracted, the value of which NGSI-LD property it represents, to which NGSI-LD Entity the property belongs and what type the Entity has. The resulting information is depicted on right side of Figure 7.2-1 and this information can be accessed through the NGSI-LD API.
+
+The extraction of values is not limited to \<contentInstance\> resources, but includes all resource types that can contain information, e.g. \<flexContainer\> or even \<semanticDescriptor\>.
+
+![Core Mca and NGSI-LD provide complementary functionality](media/Core_Mca_and_NGSI-LD_provide_complementary_functionality.png)
+
+**Figure 7.2-1: Core Mca and NGSI-LD provide complementary functionality**
+
+Figure 7.2.2 shows an example. The content instances contain values in different formats. On the left side, the content instances under Resource A contain integers, in the middle, under Resource B, the content instances each contain an XML structure.
+The semantic descriptor of Resource A contains mapping information, i.e. that the information is about an Entity with the identifer Room123, which is of type Room, has a property called indoorTemperature, whose value is to be extracted from the <contentInstance> resource, and that has a unit as meta information that indicates that the temperature is given in Celsius. The mapping information in the semantic descriptor of Resource B indicates that the information belongs to the same entity, but in this case the property is called occupancy and the information has to be extracted from the XML. The extraction examples only serve illustration purposes here, the actual format specifying how to extract information still has to be specified, taking into account suitable existing standards.
+On the right of Figure 7.2.2 the resulting NGSI-LD entity is represented that can be accessed using the NGSI-LD API.
+
+![Mapping example - oneM2M information mapped to NGSI-LD Entity](media/Mapping_example_oneM2M_information_mapped_to_NGSI-LD_Entity.png)
+
+**Figure 7.2-2: Mapping example - oneM2M information mapped to NGSI-LD Entity**
 
 # 8 Mapping between the information stored in oneM2M resources and the NGSI-LD information model
 
@@ -861,7 +898,7 @@ The following bullet points provide a summary of the NGSI-LD functionalities tha
 |-|-|-|
 |V0.1.0 |2024-04-24 |Includes the following contribution agreed during SDS64: SDS-2024-0045R01-TR-0076_Table_of_Contents |
 |V0.2.0 |2024-06-27 |Includes the following contribution agreed during SDS65: SDS_2024_0075_NGSI-LD_API_and_Information_Model |
-|V0.2.0 |2024-06-27 |Includes the following contribution agreed during SDS66: SDS-2024-0118R01-Value_provided_by_NGSI-LD_use_cases |
+|V0.3.0 |2024-09-11 |Includes the following contribution agreed during SDS66: SDS-2024-0118R01-Value_provided_by_NGSI-LD_use_cases |
 | | | |
 | | | |
 | | | |