Implement code changes to enhance functionality and improve performance

<div id="editor">

<h1 data-number="16" id="D">Annex D (informative): Transformation Algorithms</h1>

<h2 data-number="16.1" id="D.1">D.1 Introduction</h2>

<p>These algorithms are informative but NGSI-LD implementations should aim at either implementing them as they are described here or devising similar algorithms which take exactly the same input and provides exactly the same output (or an equivalent one as per the JSON-LD specification <a href="clause-2.html#n.2"><a href="clause-2.html#n.[2]"><a href="clause-2.html#n.[2]">[2]</a></a></a>).</p>

<p>These algorithms are informative but NGSI-LD implementations should aim at either implementing them as they are described here or devising similar algorithms which take exactly the same input and provides exactly the same output (or an equivalent one as per the JSON-LD specification <a href="clause-2.html#n.2"><a href="clause-2.html#n.2"><a href="clause-2.html#n.2">[2]</a></a></a>).</p>

<h2 data-number="16.2" id="D.2">D.2 Algorithm for transforming an NGSI-LD Entity into a JSON-LD document (ALG1)</h2>

<p>This algorithm takes as input an NGSI-LD graph which top level node is a particular Entity and returns as output a JSON-LD document which represents all the data associated to the entity. The JSON-LD document (and its associated <i>@context</i>) corresponds to a representation of the Entity in JSON-LD as per the NGSI-LD Information Model.</p>

<div class="NO"><div><p>NOTE:</p></div><div>

<p>An early implementation of this algorithm can be found at <a href="clause-2.html#i.5"><a href="clause-2.html#[i.5]"><a href="clause-2.html#[i.5]"><a href="clause-2.html#[i.5]"><a href="clause-2.html#[i.5]">[i.5]</a></a></a></a></a>.</p>

<p>An early implementation of this algorithm can be found at <a href="clause-2.html#i.5"><a href="clause-2.html#i.5"><a href="clause-2.html#i.5"><a href="clause-2.html#i.5"><a href="clause-2.html#i.5">[i.5]</a></a></a></a></a>.</p>

</div></div>

<p>Let:</p>

<ul>

<flex-resizer style="cursor: col-resize"></flex-resizer><flex-item style="flex: 5">

<div id="editor">

<h1 data-number="6" id="1">1 Scope</h1>

<p>The present document defines a standardized API for Context Information Management (NGSI-LD API) enabling close to real-time (right-time) access to context/digital twin information coming from many different sources (not only IoT data sources). The present document defines how such an API enables applications to perform updates on context, register context providers which can be queried to get updates on context, query information on current and historic context information and subscribe to receive notifications of context changes. The criteria for choice of the API characteristics are based on requirements resulting from the Use Cases ETSI <span>GR CIM 002 <a href="clause-2.html#[i.1]"><a href="clause-2.html#[i.1]">[i.1]</a></a></span> and other work items ETSI GR CIM 007 <a href="clause-2.html#i.2">[i.2]</a> and ETSI GS CIM 006 <a href="clause-2.html#i.8">[i.8]</a> on security and on the information model. The present document supersedes prior versions, including ETSI GS CIM 004 <a href="clause-2.html#i.16">[i.16]</a>.</p>

<p>The present document defines a standardized API for Context Information Management (NGSI-LD API) enabling close to real-time (right-time) access to context/digital twin information coming from many different sources (not only IoT data sources). The present document defines how such an API enables applications to perform updates on context, register context providers which can be queried to get updates on context, query information on current and historic context information and subscribe to receive notifications of context changes. The criteria for choice of the API characteristics are based on requirements resulting from the Use Cases ETSI <span>GR CIM 002 <a href="clause-2.html#i.1"><a href="clause-2.html#i.1">[i.1]</a></a></span> and other work items ETSI GR CIM 007 <a href="clause-2.html#i.2">[i.2]</a> and ETSI GS CIM 006 <a href="clause-2.html#i.8">[i.8]</a> on security and on the information model. The present document supersedes prior versions, including ETSI GS CIM 004 <a href="clause-2.html#i.16">[i.16]</a>.</p>

</div>

</flex-item>

</flex>

<h3 data-number="9.2.1" id="4.2.1">4.2.1 Introduction</h3>

<p>The NGSI-LD Information Model prescribes the structure of context information that shall be supported by an NGSI-LD system. It specifies the data representation mechanisms that shall be used by the NGSI-LD API itself. In addition, it specifies the structure of the Context Information Management vocabularies to be used in conjunction with the API.</p>

<p>The NGSI-LD Information Model is defined at two levels (see <a href="clause-4.html#Figure_4.2.1-1">Figure 4.2.1‑1</a>): the foundation classes which correspond to the Core Meta-model and the Cross-Domain Ontology. The former amounts to a formal specification of the “property graph” model <a href="clause-2.html#i.6">[i.6]</a>. The latter is a set of generic, transversal classes which are aimed at avoiding conflicting or redundant definitions of the same classes in each of the domain-specific ontologies. Below these two levels, domain-specific ontologies or vocabularies can be devised. For instance, the SAREF Ontology ETSI TS 103 264 <a href="clause-2.html#i.4">[i.4]</a> can be mapped to the NGSI-LD Information Model, so that smart home applications will benefit from this Context Information Management API specification.</p>

<p>The version of the cross-domain model proposed by the present document is a minimal one, aimed at defining the classes used in this release of the API specification. It has been extended by other work items like ETSI <span>GS CIM 006 <a href="clause-2.html#[i.8]"><a href="clause-2.html#[i.8]">[i.8]</a></a>,</span> with classes defining extra concepts such as mobile vs. stationary entities, instantaneous vs. static properties, etc.</p>

<p>The version of the cross-domain model proposed by the present document is a minimal one, aimed at defining the classes used in this release of the API specification. It has been extended by other work items like ETSI <span>GS CIM 006 <a href="clause-2.html#i.8"><a href="clause-2.html#i.8">[i.8]</a></a>,</span> with classes defining extra concepts such as mobile vs. stationary entities, instantaneous vs. static properties, etc.</p>

<div class="FL" id="Figure_4.2.1-1">

<p><img src="media/image2.png"/></p>

</div>

</ul>

<h3 data-number="9.5.17" id="4.5.16">4.5.16 GeoJSON Representation of Entities</h3>

<h4 data-number="9.5.17.1" id="4.5.16.0">4.5.16.0 Foreword</h4>

<p>The NGSI-LD specification defines an alternative representation of Entities, to make NGSI-LD responses compatible with GIS (Geographic Information System) applications which support the GeoJSON format <a href="clause-2.html#n.8">[8]</a> and/or <span>GeoJSON-LD <a href="clause-2.html#[i.20]"><a href="clause-2.html#[i.20]">[i.20]</a></a>.</span></p>

<p>The NGSI-LD specification defines an alternative representation of Entities, to make NGSI-LD responses compatible with GIS (Geographic Information System) applications which support the GeoJSON format <a href="clause-2.html#n.8">[8]</a> and/or <span>GeoJSON-LD <a href="clause-2.html#i.20"><a href="clause-2.html#i.20">[i.20]</a></a>.</span></p>

<p>Every NGSI-LD Entity can be represented as a GeoJSON <i>Feature</i> object, where a <i>Feature</i> object represents any spatially bounded thing as defined by its geometry.</p>

<h4 data-number="9.5.17.2" id="4.5.16.1">4.5.16.1 Top-level “geometry” field selection algorithm</h4>

<p>A parameter of the request (named <i>geometryProperty</i>) may be used to indicate the name of the <i>GeoProperty</i> to be selected. If this parameter is not present, then the default name of <span class="HTML_Code">“location”</span> shall be used.</p>

<p><strong>Mandatory</strong></p>

<ul>

<li><div class="list-item">

<p><span class="HTML_Code">“languageMap”</span>: a JSON object consisting of a set of a non-empty language tags as defined by IETF <span>RFC 5646 <a href="clause-2.html#n.[28]"><a href="clause-2.html#n.[28]"><a href="clause-2.html#n.[28]">[28]</a></a></a></span> or the language tag <span class="HTML_Code">“<span class="citation" data-cites="none">@none</span>”</span> which represents a default language, with each language tag mapping to a single string or array of strings. It represents a more specialized <i>value</i>.</p>

<p><span class="HTML_Code">“languageMap”</span>: a JSON object consisting of a set of a non-empty language tags as defined by IETF <span>RFC 5646 <a href="clause-2.html#n.28"><a href="clause-2.html#n.28"><a href="clause-2.html#n.28">[28]</a></a></a></span> or the language tag <span class="HTML_Code">“<span class="citation" data-cites="none">@none</span>”</span> which represents a default language, with each language tag mapping to a single string or array of strings. It represents a more specialized <i>value</i>.</p>

<p>An NGSI-LD Null used during partial update patch and merge patch (see clauses <a href="clause-5.html#5.5.8">5.5.8</a> and <a href="clause-5.html#5.5.12">5.5.12</a>) shall be encoded as the JSON object <span class="HTML_Code">{“<span class="citation" data-cites="none">@none</span>”: “urn:ngsi-ld:null”}</span>. The same representation is also used to indicate a deletion in notifications and in temporal evolutions for encoding a deleted <i>LanguageProperty.</i></p>

</div></li>

<li><span class="HTML_Code">“type”</span>: the fixed value <span class="HTML_Code">“LanguageProperty”</span>.</li>

<p><strong>Mandatory</strong></p>

<ul>

<li><div class="list-item">

<p><span class="HTML_Code">“languageMap”</span>: a JSON object consisting of a set of a non-empty language tags as defined by IETF <span>RFC 5646 <a href="clause-2.html#n.[28]"><a href="clause-2.html#n.[28]"><a href="clause-2.html#n.[28]">[28]</a></a></a></span> or the language tag <span class="HTML_Code">“<span class="citation" data-cites="none">@none</span>”</span>which represents a default language, with each language tag mapping to a single string or array of strings. It represents a more specialized <i>value</i>.</p>

<p><span class="HTML_Code">“languageMap”</span>: a JSON object consisting of a set of a non-empty language tags as defined by IETF <span>RFC 5646 <a href="clause-2.html#n.28"><a href="clause-2.html#n.28"><a href="clause-2.html#n.28">[28]</a></a></a></span> or the language tag <span class="HTML_Code">“<span class="citation" data-cites="none">@none</span>”</span>which represents a default language, with each language tag mapping to a single string or array of strings. It represents a more specialized <i>value</i>.</p>

<p>An NGSI-LD Null used during partial update patch and merge patch (see clauses <a href="clause-5.html#5.5.8">5.5.8</a> and <a href="clause-5.html#5.5.12">5.5.12</a>) shall be encoded as the JSON object <span class="HTML_Code">{“<span class="citation" data-cites="none">@none</span>”: “urn:ngsi-ld:null”}</span>. The same representation is also used to indicate a deletion in notifications and the temporal evolutions for encoding a deleted <i>LanguageProperty</i>.</p>

</div></li>

</ul>