Contribution SDS-2025-0014R01 Mapping Approach for Integrating NGSI-LD into...

Contribution SDS-2025-0014R01 Mapping Approach for Integrating NGSI-LD into oneM2M Architecture merged into R5

Original contribution: SDS-2025-0014-Mapping_Approach_for_integrating_NGSI-LD_into_oneM2M_Architecture

See merge request !9

TR-0076-Integrating_NGSI-LD_API_in_oneM2M.md

@@ -797,21 +797,78 @@ Applications have the following interaction options using NGSI-LD:
 
 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.
+Figure 7.2.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.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-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.
+Figure 7.2.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.
+On the right of Figure 7.2.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**
+**Figure 7.2.2-2: Mapping example - oneM2M information mapped to NGSI-LD Entity**
+
+### 7.2.3 Integration in oneM2M architecture
+
+NGSI-LD provides a new set of functionalities to oneM2M, thus it should be its own CSF (logical grouping of functionalities), see Figure 7.2.3-1. The name of such a new CSF is up for discussion, e.g. NGSI-LD,  Context Management or Context Information Access.
+
+![NGSI-LD as CSF in oneM2M](media/NGSI-LD-CSF.png)
+
+**Figure 7.2.3-1: NGSI-LD as CSF in oneM2M**
+
+The NGSI-LD API also needs to be added to one or more oneM2M reference points. It can be added to one or more existing reference points. Alternatively, one or more additional reference points could be added. Figure 7.2.3-2 shows the options and Table 7.2.3-1 discusses pros and cons for adding NGSI-LD to existing reference point(s).
+
+![NGSI-LD ](media/NGSI-LD_in_oneM2M_Reference_Points.png)
+
+**Figure 7.2.3-2: NGSI-LD in oneM2M reference points**
+
+|Pros|Cons|
+|---|---|
+|Interaction is between the same oneM2M Entities – AE and CSE (or CSE and CSE)|Core Mca and NGSI-LD make very different assumptions, resulting in a heterogeneous reference point. oneM2M is a resource-based architecture with a REST interface, whereas NGSI-LD is a functional API based on the NGSI-LD entity concept, with a REST binding (REST resources are either defined in the specification or are derived from NGSI-LD Entity structure – they cannot be freely created)|
+
+**Table 7.2.3-1: Pros and Cons for adding NGSI-LD to existing reference point(s)**
+
+NGSI-LD foresees distributed operations based on registrations as shown in Figure 7.2.3-3. If one CSEs registers with another CSE (e.g. parent CSE), information can be transparently accessed through the CSE to CSE connection.
+
+![NGSI-LD between CSEs](media/NGSI-LD_between_CSEs.png)
+
+**Figure 7.2.3-3: NGSI-LD between CSEs**
+
+Figure 7.2.3-4 shows the NGSI-LD REST/HTTP binding. NGSI-LD resources are either static, i.e. exist from the start as defined in the NGSI-LD specification, or are implicitly defined by the information. For example, an NGSI-LD Entity is created and as a result one or more resources exist, so information is created/updated/deleted/queried etc., not resources as such, and there can be multiple ways to create the same information – e.g. as individual entity or via batch operations.
+
+![NGSI-LD REST/HTTP Binding](media/Statically_and_implicitly_deined_NGSI-LD_resources.png)
+
+**Figure 7.2.3-4: NGSI-LD REST/HTTP binding**
+
+In the proposed mapping approach, NGSI-LD resources would be implicitly created through the mapping information.
+
+The following base path / resource is defined in the NGSI-LD Specification <a href="#_ref_i.2">[i.2]</a> and thus always exists: 
+```
+<path>/ngsi-ld/v1/entities
+```
+
+Here `<path>` is used as a placeholder. In oneM2M the respective binding and addressing needs to be taken into account that enables targetting the ngsi-ld resource. This is going to be discussed separately, and the remainder of the path is used to target the relevant subresource. 
+
+By adding the mapping as shown in Figure 7.2.3-5, the following resources would implicitly become available:
+```
+<path>/ngsi-ld/v1/entities/urn:Room123
+<path>/ngsi-ld/v1/entities/urn:Room123/attrs/indoorTemperature
+```
+
+![Implicit resource creation by adding mapping](media/Implicit_resource_creation_by_adding_mapping.png)
+
+**Figure 7.2.3-5: Implicit resource creation by adding mapping**
+
+The final question is how to anchor the NGSI-LD base resource `ngsi-ld` into the oneM2M resource structure. As shown in Figure 7.2.3-6, the proposal is to add it as a child resource of CSEBase.
+
+![NGSI-LD resource as child resource of CSE Base](media/NGSI-LD_as_child_of_CSE_Base.png)
+
+**Figure 7.2.3-6: NGSI-LD resource as child resource of CSE Base**
 
 # 8 Mapping between the information stored in oneM2M resources and the NGSI-LD information model