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.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 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>.

Figure 7.2.2-1: Core Mca and NGSI-LD provide complementary functionality

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 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-2 the resulting NGSI-LD entity is represented that can be accessed using the NGSI-LD API.

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.

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).

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.

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.

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 [i.2] 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

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.

Figure 7.2.3-6: NGSI-LD resource as child resource of CSE Base