4 Context Information Management Framework

4.1 Introduction

The present clause describes the technical design principles behind the context information management framework supported by NGSI-LD. As stated in clause 3.1, the letters “NGSI-LD” which are part of most terms, to confirm that they are distinct from other terms of similar/same name in use in other organizations, are generally omitted in the present document for brevity. In the present document, a number of rather obvious typographic conventions and syntax guidelines are followed, and the reader is referred to annex F for details.

4.2 NGSI-LD Information Model

4.2.1 Introduction

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.

The NGSI-LD Information Model is defined at two levels (see Figure 4.2.1‑1): 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 [i.6]. 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 [i.4] can be mapped to the NGSI-LD Information Model, so that smart home applications will benefit from this Context Information Management API specification.

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 GS CIM 006 [i.8], with classes defining extra concepts such as mobile vs. stationary entities, instantaneous vs. static properties, etc.

Figure 4.2.1-1: Overview of the NGSI-LD Information Model Structure

4.2.2 NGSI-LD Meta Model

Figure 4.2.2‑1 provides a graphical representation of the NGSI-LD Meta-Model in terms of classes and their relationships. To provide additional clarity an informal (non-normative) mapping to the Property Graph Model is also presented.

Legend:

	[With capital initial]. Used to refer to a class that is a subclass of Entity or Value.
	[With capital initial]. Used to refer to a class that is a subclass of Property or Relationship, but which is not itself a property or a relationship. These classes serve as super-classes for a set of properties or relationships in the same domain or aspect.
and	[With small initial]. Used to refer to a proper (direct) class of properties or relationships.
	[With small initial and underlined text]. Used to refer to the name of a property that is considered to be “lite” in its informational representation since it shall not be reified, rather a value is directly attached to it.
	[With small or capital initial]. Used to refer to a class or a vocabulary that is inherited from another publicly available standard or ontology.

Figure 4.2.2-1: NGSI-LD Core Meta-Model

Implementations shall support the NGSI-LD Meta-model as follows:

An NGSI-LD Entity is a subclass of rdfs:Resource [1].
An NGSI-LD Relationship is a subclass of rdfs:Resource [1].
An NGSI-LD Property is a subclass of rdfs:Resource [1].
An NGSI-LD Value shall be either a rdfs:Literal or a node object (in JSON-LD syntax) to represent complex data structures [1].
An NGSI-LD Property shall have a value, stated through hasValue, which is of type rdf:Property [1]. An NGSI-LD Relationship shall have an object stated through hasObject which is of type rdf:Property [1].

4.2.3 Cross Domain Ontology

Legend:

	[With capital initial]. Used to refer to a class that is a subclass of Entity or Value.
	[With capital initial]. Used to refer to a class that is a subclass of Property or Relationship, but which is not itself a property or a relationship. These classes serve as super-classes for a set of properties or relationships in the same domain or aspect.
and	[With small initial]. Used to refer to a proper (direct) class of properties or relationships.
	[With small initial and underlined text]. Used to refer to the name of a property that is considered to be “lite” in its informational representation since it shall not be reified, rather a value is directly attached to it.
	[With small or capital initial]. Used to refer to a class or a vocabulary that is inherited from another publicly available standard or ontology.

Figure 4.2.3-1: NGSI-LD Core Meta-Model plus the Cross-Domain Ontology

Figure 4.2.3‑1 describes the concepts introduced by the NGSI-LD Cross-Domain Ontology, which shall be supported by implementations as follows:

Geo Properties: Are intended to convey geospatial information and implementations shall support them as defined in clause 4.7.
Temporal Properties: Are non-reified Properties (represented only by their Value) that convey temporal information for capturing the time series evolution of other Properties; implementations shall support them as defined in clause 4.8.
Language Properties: Are intended to convey different versions of the same textual values, whenever a version for each language (for instance: English, Spanish) is needed.
“unitCode” Property: Is a Property intended to provide the units of measurement of an NGSI-LD Value. Implementations shall support it as defined in clause 4.5.2.
“scope” Property: Is a Property that enables putting Entities into a hierarchical structure. Implementations shall support it as defined in clause 4.18.
LanguageMaps: Are a special type of NGSI-LD Value intended to convey the different values of Language Properties, stated through an hasLanguageMap, which is of type rdf:Property [1] and is itself a subproperty of hasValue.
Geometry Values: Are a special type of NGSI-LD Value intended to convey geometries corresponding to geospatial properties. Implementations shall support them as defined in clause 4.7.
Time Values: Are a special type of NGSI-LD Value intended to convey time instants or intervals representations. Implementations shall support them as defined in clause 4.6.3.

Clause 4.4 defines the Core JSON-LD @context which includes the URIs which correspond to the concepts introduced above.

4.2.4 NGSI-LD domain-specific models and instantiation

This clause is informative and is intended to illustrate the relationship between the NGSI-LD Information Model and NGSI-LD Domain-specific models.

Figure 4.2.4‑1 shows an example of an NGSI-LD domain-specific model. Domain-specific models introduce the specific entity types required for a particular domain. Figure 4.2.4‑1 shows the types “Car”, “Parking”, “Street”, “Gate”. Entity types can have further subtypes, e.g. “OffStreetParking” as subtype of “Parking”.

Figure 4.2.4-1: Cross-Domain Ontology and instantiation

In addition, two different NGSI-LD Properties are introduced (hasState, reliability).

The adjacentTo Relationship links entities of type “Parking” with entities of type “Street”.

4.2.5 UML representation

This clause is informative and is intended to show how the NGSI-LD information model could be described using UML diagrams. The aim of this diagram is to help those readers less familiar with ontology representations or RDF [1] to understand the NGSI-LD Information Model.

In Figure 4.2.5‑1 NGSI-LD Entity, Relationship, Property and Value are represented as UML classes. UML associations are used to interrelate these classes while keeping the structure and semantics defined by the NGSI-LD Information Model.

Figure 4.2.5-1: NGSI-LD information model as UML

4.3 NGSI-LD Architectural Considerations

4.3.1 Introduction

The NGSI-LD API is intended to be primarily an API and does not define a specific architecture. It is envisioned that the NGSI-LD API can be used in different architectural settings and the architectural assumptions of the API are kept to a minimum.

As it is not possible to elaborate all possible architectures in which the NGSI-LD API could be used, three prototypical architectures are presented. The NGSI-LD API shall enable efficient support for all of them, i.e. the design decisions for the NGSI-LD API take these prototypical architectures into consideration. A real system architecture utilizing the NGSI-LD API can map to one, take elements from multiple or combine all of the prototypical architectures.

The NGSI-LD API implicitly defines two sets of Entities:

the “current state”;
the “temporal evolution” (both the past and possibly future predictions).

The NGSI-LD API is structured into a Core API and an optional Temporal API. The Core API manages the current state of Entities. The Temporal API is optional and manages the Temporal Evolution of Entities. Brokers that intend to implement the Temporal API should consider updating the Temporal Evolution of an Entity whenever the “current state” is modified via the Core API.

4.3.2 Centralized architecture

Figure 4.3.2‑1 shows a centralized architecture. In the centre is a Central Broker that stores all the context information. There are Context Producers that use update operations to update the context information in the Central Broker and there are Context Consumers that request context information from the Central Broker, either using synchronous one-time query or asynchronous subscribe/notify operations. The Central Broker answers all requests from its storage. Figure 4.3.2‑1 shows one component that acts as both Context Producer and Context Consumer. The general assumption is that components can have multiple roles, so such components are not explicitly shown in clauses 4.3.3 and 4.3.4.

Figure 4.3.2-1: Centralized architecture

4.3.3 Distributed architecture

Figure 4.3.3‑1 shows a distributed architecture. The underlying idea here is that all information is stored by the Context Sources. Context Sources implement the query and subscription part of the NGSI-LD API as a Context Broker does. They register themselves with the Context Registry, providing information about what context information they can provide, but not the context information itself, e.g. a certain Context Source registers that it can provide the indoor temperature for Building A and Building B or that it can provide the speed of cars in a geographic region covering the centre of a city.

Figure 4.3.3-1: Distributed architecture

Context Consumers can query or subscribe to the Distribution Broker. On each request, the Distribution Broker discovers or does a discovery subscription to the Context Registry for relevant Context Sources, i.e. those that may provide context information relevant to the respective request from the Context Consumer. The Distribution Broker then queries or subscribes to each relevant Context Source, if possible it aggregates the context information retrieved from the Context Sources and provides them to the Context Consumer. In this mode of operation, it is not visible to the Context Consumer, whether the Context Broker is a Central Broker or a Distribution Broker. Alternatively, the architecture allows that Context Consumers can discover Context Sources through the Context Registry themselves and then directly request from Context Sources. This is shown in Figure 4.3.3‑1 with the fine dashed arrows.

4.3.4 Federated architecture

The federated architecture shown in Figure 4.3.4‑1 is used in cases where existing domains are to be federated. For example, different departments in a city operate their own Context Broker-based NGSI-LD infrastructure, but applications should be able to easily access all available information using just one point of access. The architecture works in the same way as the distributed architecture described in clause 4.3.3, except that instead of simple Context Sources, whole domains are registered with the respective Context Broker as point of access. Typically, the domains will be registered to the federation Context Registry on a more coarse-grained level, providing scopes, in particular geographic scopes, that can then be matched to the scopes provided in the requests. For example, instead of registering individual entities like buildings, the domain would be registered with having information about entities of type building within a geographic area. Applications then query or subscribe for entities within a geographic scope, e.g. buildings in a certain area of the city. The Federation Broker discovers the domain Context Brokers that can provide relevant information, forwards the request to these Context Brokers and aggregates the results, so the application gets the result in the same way as in the centralized and distributed cases.

Figure 4.3.4-1: Federated architecture

A domain itself can use a centralized or distributed architecture or could even utilize a federated architecture that federates sub-domains.

As in the distributed case, it is also possible that applications discover relevant domains through the federation-level Context Registry and directly contact the Context Brokers in the individual domains.

4.3.5 NGSI-LD API Structure and Implementation Options

As stated in clause 4.3.1, the NGSI-LD API is structured into a Core API and an optional Temporal API. To support the distributed and federated architectures described in clauses 4.3.3 and 4.3.4 respectively, distributed versions of the operations are needed. They are listed separately under Distributed API and require the operations of the Registry API. The Registry API consists of the operations to be implemented by the Context Registry. Furthermore, the JSONLDContext API provides functionality for storing, managing, and serving JSON-LD @contexts. The APIs are structured according to their functionalities, which is also reflected in how the operations are structured in clause 5. Table 4.3.5‑1 introduces the API structure, the respective functionalities and lists the operations for each functionality, pointing to the clauses in which they are defined. The distributed versions of the operations are separately shown in Table 4.3.5‑1 under Distributed API, but there is a single clause for each of the operations describing both the centralized and distributed behaviour. In addition, the Distributed API has support operations only needed in distributed and federated architectures.

Table 4.3.5-1: NGSI-LD API structure

API	Functionality	Operations
Core API	Context Information Provision - operations for providing or managing Entities and Attributes	5.6.1 Create Entity 5.6.2 Update Attributes 5.6.3 Append Attributes 5.6.4 Partial Attribute Update 5.6.5 Delete Attribute 5.6.6 Delete Entity 5.6.7 Batch Entity Creation 5.6.8 Batch Entity Upsert 5.6.9 Batch Entity Update 5.6.10 Batch Entity Delete 5.6.17 Merge Entity 5.6.18 Replace Entity 5.6.19 Replace Attribute 5.6.20 Batch Entity Merge
	Context Information Consumption - operations for consuming Entities and checking for which Entity Types and Attributes Entities are available in the system	5.7.1 Retrieve Entity 5.7.2 Query Entities 5.7.5 Retrieve Available Entity Types 5.7.6 Retrieve Details of Available Entity Types 5.7.7 Retrieve Available Entity Type Information 5.7.8 Retrieve Available Attributes 5.7.9 Retrieve Details of Available Attributes 5.7.10 Retrieve Available Attribute Information
	Context Information Subscription - operations for subscribing to Entities, receiving notifications and managing subscriptions	5.8.1 Create Subscription 5.8.2 Update Subscription 5.8.3 Retrieve Subscription 5.8.4 Query Subscription 5.8.5 Delete Subscription 5.8.6 Notification
Temporal API	Temporal Context Information Provision - operations for providing or managing the Temporal Evolution of Entities and Attributes	5.6.11 Upsert Temporal Evolution of an Entity 5.6.12 Add Attributes to Temporal Evolution of an Entity 5.6.13 Delete Attributes from Temporal Evolution of an Entity 5.6.14 Partial Update Attribute instance 5.6.15 Delete Attribute Instance 5.6.16 Delete Temporal Evolution of an Entity
Temporal API	Temporal Context Information Consumption - operations for consuming the Temporal Evolution of Entities	5.7.3 Retrieve Temporal Evolution of an Entity 5.7.4 Query Temporal Evolution of Entities
Distributed API	Distributed Context Information Provision - operations for providing or managing Entities and Attributes	5.6.1 Create Entity (distributed) 5.6.2 Update Attributes (distributed) 5.6.3 Append Attributes (distributed) 5.6.4 Partial Attribute Update (distributed) 5.6.5 Delete Attribute (distributed) 5.6.6 Delete Entity (distributed) 5.6.7 Batch Entity Creation (distributed) 5.6.8 Batch Entity Upsert (distributed) 5.6.9 Batch Entity Update (distributed) 5.6.10 Batch Entity Delete (distributed) 5.6.17 Merge Entity (distributed) 5.6.18 Replace Entity (distributed) 5.6.19 Replace Attribute (distributed) 5.6.20 Batch Entity Merge (distributed)
	Distributed Context Information Consumption - operations for consuming Entities and checking for which Entity Types and Attributes Entities are available in the system	5.7.1 Retrieve Entity (distributed) 5.7.2 Query Entities (distributed) 5.7.5 Retrieve Available Entity Types (distributed) 5.7.6 Retrieve Details of Available Entity Types (distributed) 5.7.7 Retrieve Available Entity Type Information (distributed) 5.7.8 Retrieve Available Attributes (distributed) 5.7.9 Retrieve Details of Available Attributes (distributed) 5.7.10 Retrieve Available Attribute Information (distributed)
	Distributed Context Information Subscription - operations for subscribing to Entities, receiving notifications and managing subscriptions	5.8.1 Create Subscription (distributed) 5.8.2 Update Subscription (distributed) 5.8.3 Retrieve Subscription (distributed) 5.8.4 Query Subscription (distributed) 5.8.5 Delete Subscription (distributed) 5.8.6 Notification (distributed)
	Distributed Temporal Context Information Provision - operations for providing or managing the Temporal Evolution of Entities and Attributes	5.6.11 Upsert Temporal Evolution of an Entity (distributed) 5.6.12 Add Attributes to Temporal Evolution of an Entity (distributed) 5.6.13 Delete Attributes from Temporal Evolution of an Entity (distributed) 5.6.14 Partial Update Attribute instance (distributed) 5.6.15 Delete Attribute Instance (distributed) 5.6.16 Delete Temporal Evolution of an Entity (distributed)
	Distributed Temporal Context Information Consumption - operations for consuming the Temporal Evolution of Entities	5.7.3 Retrieve Temporal Evolution of an Entity (distributed) 5.7.4 Query Temporal Evolution of Entities (distributed)
	Support operations for distributed operations	5.14.1 Retrieve EntityMap 5.14.2 Update EntityMap 5.14.3 Delete EntityMap 5.14.4 Create EntityMap for Query Entities 5.14.5 Create EntityMap for Query Temporal Evolution of Entities 5.15.1 Retrieve Context Source Identity Information
Registry API	Context Source Registration - operations for registering Context Sources and managing Context Source Registrations (CSRs)	5.9.2 Register Context Source 5.9.3 Update CSR 5.9.4 Delete CSR
	Context Source Discovery - operations for retrieving and discovering CSRs	5.7.1 Retrieve CSR 5.7.2 Query CSRs
	Context Source Registration Subscription - operations for subscribing to CSRs, receiving notifications and managing CSRs	5.11.2 Create CSR Subscription 5.11.3 Update CSR Subscription 5.11.4 Retrieve CSR Subscription 5.11.5 Query CSR Subscription 5.11.6 Delete CSR Subscription 5.11.7 CSR Notification
Snapshot API	Operations for creating and managing Snapshots.	5.16.1 Create Snapshot 5.16.2 Clone Snapshot 5.16.3 Retrieve Snapshot Status 5.16.4 Update Snapshot Status 5.16.5 Delete Snapshot 5.16.6 Snapshot Status Notification
JSONLDContext API	Storing, managing and serving@contexts	5.13.2 Add @context 5.13.3 List @contexts 5.13.4 Serve @context 5.13.5 Delete and Reload @context

All Context Brokers shall implement the Core API. Context Brokers supporting distributed and federated deployments shall also implement the Distributed API. Temporal API and Registry API can be implemented by a Broker or by a separate temporal component and Context Registry respectively. Table 4.3.5‑2 shows the possible implementation configurations. A temporal component implementing the Temporal API can also be used completely independently of a Context Broker. The Snapshot API and the JSONLDContext API are optional. The managing and serving of @contexts can also be handled by an independent, stand-alone component.

Table 4.3.5-2: Main implementation configurations

Description	Temporal API	RegistryAPI
Central Broker without temporal support	none	none
Central Broker with integrated temporal component	local	none
Central Broker with separate temporal component	separate	none
Context Broker supporting distributed and federated deployments without temporal support and with integrated Context Registry	none	local
Context Broker supporting distributed and federated deployments with integrated temporal component and integrated Context Registry	local	local
Context Broker supporting distributed and federated deployments with separate temporal component and integrated Context Registry	separate	local
Context Broker supporting distributed and federated deployments without temporal support and separate Context Registry	none	separate
Context Broker supporting distributed and federated deployments with integrated temporal component and separate Context Registry	local	separate
Context Broker supporting distributed and federated deployments with separate temporal component and separate Context Registry	separate	separate

Table 4.3.5‑3 shows which operations are implemented and used by the other architectural roles as introduced in clause 4.3.2, clause 4.3.3 and clause 4.3.4. In addition, there are separate roles for the Temporal API, i.e. Temporal Context Producer, Temporal Context Source and Temporal Context Consumer. For completeness, the roles of Context Repository and Temporal Context Repository have been introduced, implementing the Context Information Provision and Temporal Context Information Provision functionalities, respectively. In practice, components implementing the latter roles will also implement functionalities for consuming or processing the stored information. Actual components can have multiple roles at the same time, e.g. a Context Broker can implement all roles at the same time. Context Consumers typically only interact with Context Brokers, but in alternative setups, as shown in Figure 4.3.3‑1, they can also directly interact with the Context Registry and then directly contact Context Sources.

Table 4.3.5-3: Operations implemented by the various NGSI-LD Roles

NGSI-LD Role	Implements	Uses
Context Consumer	5.8.6 Notification - if supporting asynchronous interactions In case of direct interactions with Context Registry: 5.11.7 CSR Notification -if supporting asynchronous interactions	5.7.1 Retrieve Entity 5.7.2 Query Entities 5.7.5 Retrieve Available Entity Types 5.7.6 Retrieve Details of Available Entity Types 5.7.7 Retrieve Available Entity Type Information 5.7.8 Retrieve Available Attributes 5.7.9 Retrieve Details of Available Attributes 5.7.10 Retrieve Available Attribute Information 5.8.1 Create Subscription 5.8.2 Update Subscription 5.8.3 Retrieve Subscription 5.8.4 Query Subscription 5.8.5 Delete Subscription 5.14.1 Retrieve EntityMap 5.14.2 Update EntityMap 5.14.3 Delete EntityMap 5.14.4 Create EntityMap for Query Entities 5.14.5 Create EntityMap for Query Temporal Evolution of Entities 5.15.1 Retrieve Context Source Identity Information 5.16.1 Create Snapshot 5.16.2 Clone Snapshot 5.16.3 Retrieve Snapshot Status 5.16.4 Update Snapshot Status 5.16.5 Delete Snapshot 5.16.6 Snapshot Status Notification In case of direct interactions with Context Registry: 5.7.1 Retrieve CSR 5.7.2 Query CSRs if supporting asynchronous interactions: 5.11.2 Create CSR Subscription 5.11.3 Update CSR Subscription 5.11.4 Retrieve CSR Subscription 5.11.5 Query CSR Subscription 5.11.6 Delete CSR Subscription
Context Producer	none	5.6.1 Create Entity 5.6.2 Update Attributes 5.6.3 Append Attributes 5.6.4 Partial Attribute Update 5.6.5 Delete Attribute 5.6.6 Delete Entity 5.6.7 Batch Entity Creation 5.6.8 Batch Entity Upsert 5.6.9 Batch Entity Update 5.6.10 Batch Entity Delete 5.6.17 Merge Entity 5.6.18 Replace Entity 5.6.19 Replace Attribute 5.6.20 Batch Entity Merge
Context Source	5.7.1 Retrieve Entity 5.7.2 Query Entities 5.7.5 Retrieve Available Entity Types 5.7.6 Retrieve Details of Available Entity Types 5.7.7 Retrieve Available Entity Type Information 5.7.8 Retrieve Available Attributes 5.7.9 Retrieve Details of Available Attributes 5.7.10 Retrieve Available Attribute Information 5.8.1 Create Subscription 5.8.2 Update Subscription 5.8.3 Retrieve Subscription 5.8.4 Query Subscription 5.8.5 Delete Subscription 5.14.1 Retrieve EntityMap 5.14.2 Update EntityMap 5.14.3 Delete EntityMap 5.14.4 Create EntityMap for Query Entities 5.14.5 Create EntityMap for Query Temporal Evolution of Entities5.15.1 Retrieve Context Source Identity Information	5.8.6 Notification 5.9.2 Register Context Source 5.9.3 Update CSR 5.9.4 Delete CSR
Context Repository	5.6.1 Create Entity 5.6.2 Update Attributes 5.6.3 Append Attributes 5.6.4 Partial Attribute Update 5.6.5 Delete Attribute 5.6.6 Delete Entity 5.6.7 Batch Entity Creation 5.6.8 Batch Entity Upsert 5.6.9 Batch Entity Update 5.6.10 Batch Entity Delete 5.6.17 Merge Entity 5.6.18 Replace Entity 5.6.19 Replace Attribute 5.6.20 Batch Entity Merge 5.16.1 Create Snapshot 5.16.2 Clone Snapshot 5.16.3 Retrieve Snapshot Status 5.16.4 Update Snapshot Status 5.16.5 Delete Snapshot 5.16.6 Snapshot Status Notification	none
Temporal Context Consumer	In case of direct interactions with Context Registry: 5.11.7 CSR Notification - if supporting asynchronous interactions	5.7.3 Retrieve Temporal Evolution of an Entity 5.7.4 Query Temporal Evolution of Entities In case of direct interactions with Context Registry: 5.7.1 Retrieve CSR 5.7.2 Query CSRs if supporting asynchronous interactions: 5.11.2 Create CSR Subscription 5.11.3 Update CSR Subscription 5.11.4 Retrieve CSR Subscription 5.11.5 Query CSR Subscription 5.11.6 Delete CSR Subscription
Temporal Context Producer	None	5.6.11 Upsert Temporal Evolution of an Entity 5.6.12 Add Attributes to Temporal Evolution of an Entity 5.6.13 Delete Attributes from Temporal Evolution of an Entity 5.6.14 Partial Update Attribute instance 5.6.15 Delete Attribute Instance 5.6.16 Delete Temporal Evolution of an Entity
Temporal Context Source	5.7.3 Retrieve Temporal Evolution of an Entity 5.7.4 Query Temporal Evolution of Entities	5.9.2 Register Context Source 5.9.3 Update CSR 5.9.4 Delete CSR
Temporal Context Repository	5.6.11 Upsert Temporal Evolution of an Entity 5.6.12 Add Attributes to Temporal Evolution of an Entity 5.6.13 Delete Attributes from Temporal Evolution of an Entity 5.6.14 Partial Update Attribute instance 5.6.15 Delete Attribute Instance 5.6.16 Delete Temporal Evolution of an Entity	none
Context Registry	5.9.2 Register Context Source 5.9.3 Update CSR 5.9.4 Delete CSR 5.7.1 Retrieve CSR 5.7.2 Query CSRs 5.11.2 Create CSR Subscription 5.11.3 Update CSR Subscription 5.11.4 Retrieve CSR Subscription 5.11.5 Query CSR Subscription 5.11.6 Delete CSR Subscription	5.11.7 CSR Notification

4.3.6 Distributed Operations

4.3.6.1 Introduction

One fundamental concept underpinning all of the prototypical architectures described above (clauses 4.3.2, 4.3.3 and 4.3.4) is the idea that Entity data does not need to be centralized within a single Context Broker. When reading context information, a Context Broker can be used as a single point of access to retrieve Entity data found distributed across multiple associated Context Brokers each receiving a context consumption request. Similarly, when modifying an Entity, a single request to a Context Broker may result in the operation being distributed and different parts of that Entity being updated across multiple Context Brokers each receiving a context provision request.

As long as there is only a centralized Context Broker, i.e. there are no Context Sources registered, all NGSI-LD requests, with few exceptions such as Update Attributes (see clause 5.6.2) and the batch operations (see clauses 5.6.7, 5.6.8, 5.6.9, 5.6.10 and 5.6.20), can either be successfully executed completely, or result in an error. In the distributed case, all requests can be partially successful. For the centralized case described above, only specific operations, such as Update Attributes and the batch operations, can be partially successful.

It is the responsibility of the Context Broker to respect the registration parameters when issuing distributed requests. For instance, if a registration states that only Entities of a given type are offered, the distributed request does not contain additional types. Such a strict requirement is justified because Context Sources (the receivers of the distributed request) are not in a position to determine whether a request has been triggered by a registration, rendering them unable to ensure that the registration parameters are respected in the first place. This applies for any kind of context data a Context Broker can exchange such as Entity IDs, entity types, attribute names, geofenced areas, etc. Ultimately, all constraints specified in the registration shall be respected.

When a Context Source is registered, an operation mode is selected. This defines the basis for distributed operations and also defines whether or not the Context Broker is permitted to hold context data about the Entities and Attributes locally itself.

If two registered Context Sources are providing context data for the same Attribute, the Attribute instances can be distinguished by datasetId. The mechanism for determining which data shall be returned is defined in clause 4.5.5.

It is possible to restrict a registered Context Source to operate on a specific Entity type or list of Entity types. In order for Context Broker hierarchies to support and restrict the distribution of such limited operations, the Entity type selector (see clause 4.17) can be added as a filter on forwarded requests even where its presence initially seems redundant.

Furthermore, registered Context Sources may indicate that they are only willing to respond to a limited subset of API operations. Context Brokers shall respect this, to avoid unnecessarily sending distributed operation requests which are always guaranteed to fail. For example, a Context Source may consistently refuse certain API operations since it does not support them. Alternatively, some Context Source endpoints (such as updates) may be protected for use by authorized users only, and not accessible to a Context Broker without those rights. Limited access is likely to be the case in extended data sharing scenarios, where a registered Context Source, and the data held within it, may belong to an external third party.

For the endpoints served, all registered Context Sources shall support the normalized representation of Entities as default. Support of additional representation formats is optional and will depend on the implementation. System generated attributes such as modifiedAt and createdAt (see clause 4.8) should be supported by registered Context Sources, at a minimum no error shall be returned if they are not available when requested.

4.3.6.2 Additive Registrations

For additive registrations, the Context Broker is permitted to hold context data about the Entities and Attributes locally itself, and also obtain data from external sources. Context provisioning operations are serviced both locally by the Context Broker itself, and also distributed on to the registered sources.

An inclusive Context Source Registration specifies that the Context Broker considers all registered Context Sources as equals and will distribute operations to those Context Sources even if relevant context data is available directly within the Context Broker itself (in which case, all results will be integrated in the final response). Data from everyContext Source registered by an inclusive Context Source Registration is requested with an equal priority. This is the default mode of operation.

An auxiliary Context Source Registration never overrides data held directly within a Context Broker. Auxiliary distributed operations are limited to context information consumption operations (see clause 5.7). Context data from auxiliary context sources is only included if it is supplementary to the context data otherwise available to the Context Broker. Auxiliary Context Source Registrations are always accepted as there can never be a conflict.

4.3.6.3 Proxied Registrations

For proxied registrations, the Context Broker itself is not permitted to hold context data about the registered Entities and Attributes locally (thus all registered context data is obtained from the external registered sources). Unregistered Attributes of an Entity are permitted to be held locally; when context provisioning operations are received, registered Attributes are distributed on to the registered sources and never serviced directly by the Context Broker itself.

An exclusive Context Source Registration specifies that all of the registered context data is held in a single location external to the Context Broker. The Context Broker itself holds no data locally about the registered Attributes and no overlapping proxied Context Source Registrations shall be supported for the same combination of registered Attributes on the Entity. An exclusive registration shall always relate to specific Attributes found on a single Entity. Thus, the registration shall define both:

An entity id (i.e. an id pattern or Entity type defining a group of entities is not supported for exclusive registrations).
Attributes.

Once an exclusive Context Source Registration has been created, no further exclusive or redirect Context Source Registrations can be created for that same combination of Entity ID and Attributes.

A redirect Context Source Registration also specifies that the registered context data is held in a location external to the Context Broker. It is possible to register (any combination of):

A whole Entity by id or id pattern (i.e. without specifying individual Attributes in the registration; in this case, all Attributes are held externally).
Entities by Entity type only (with or without specifying individual Attributes).
Attributes only.

Potentially multiple distinct redirect registrations can apply at the same time. The Context Brokeritself holds no data locally in conflict to the registration. In the case that multiple overlapping redirect registrations are defined, operations are distributed to all registered Context Sources.

4.3.6.4 Limiting Cascading Distributed Operations

When creating a registration, it is unknown whether the requested data is held at the distributed endpoint, or it is in turn distributed via further registrations. It is necessary to include a binding-specific mechanism to request operations only on the registered endpoint itself to avoid cascades of an excessive lengths, duplicates or loops.

Furthermore, it is not known if any distributed endpoints of a registered Context Sourceare in turn reliant on previously encountered Context Sources thus causing an infinite loop. Therefore, when processing a distributed operation, a specific field listing all previously encountered Context Sources(e.g. a Via header in the response in case of HTTP binding (IETF RFC 7230 [27])) shall be passed as part of the request and this field can be used to exclude duplicated sources from matching as context source registrations.

In the case of multi-tenancy (see clause 4.14) each Tenant found within each registered Context Source shall be considered separately.

4.3.6.5 Extra information to provide when contacting Context Source

If the optional array (of KeyValuePair type, as defined by clause 5.2.22) contextSourceInfo of the CSourceRegistration is present, it contains, whatever extra information the Context Broker shall convey when contacting the Context Source. This can be information the Context Broker needs to successfully communicate with the Context Source (e.g. Authorization material), or for the Context Source to correctly interpret the received content (e.g. the Link URL to fetch an @context). The method for conveying this information is binding-specific, e.g. using headers in the case of HTTP. Instead of providing the actual value, the special value “urn:ngsi-ld:request” can be used to indicate that the respective value is to be taken from the request that triggered the given request, if present.

EXAMPLE:

If the key value pair “user”: “urn:ngsi-ld:request” is part of contextSourceInfo of the CSourceRegistration, the Context Broker checks if “user” was conveyed in the triggering request. If this is the case, e.g. “user”: “abcd” , “user”: “abcd” is also conveyed when contacting the Context Source .

As Tenant information, if applicable, is directly specified in the CSourceRegistration, it shall not be part of contextSourceInfo. Binding-specific information that is used for setting up the connection or is specific for an interaction, e.g. Content-length in HTTP, cannot be overridden by contextSourceInfo. If present, such information shall be ignored.

4.3.6.6 Additional pre- and post-processing of extra information when contacting Context Source

The following key-values have a specific well-defined meaning when defined as elements within the optional array contextSourceInfo of the CSourceRegistration.

If the key “accept” is defined:

the value shall be a MIME type acceptable to the Context Broker (one of: “application/json”,“application/ld+json”) .
the response from the distributed endpoint shall be returned in this defined format and if necessary, the Context Broker shall be responsible for converting this to the desired content type when aggregating responses to the initial request.

If the key “contentType” is defined:

the value shall be a MIME type acceptable to the Context Broker (one of: “application/json”,“application/ld+json”) .
theContext Broker shall provide the request and the associated @context as required by the MIME type when distributing the request to the context source endpoint, regardless of how it was provided in the initial request.

If the key “jsonldContext”is defined:

the value shall correspond to a URL reference as defined by the JSON-LD specification [2], section 3.1.
the Context Broker shall apply a compaction operation as defined by the JSON-LD specification [2], section 4.1.5 over both payload and query parameters using the JSON-LD Context supplied in the value of the “jsonldContext” key-value pair, prior to distributing the request to the context source endpoint and forwarding with this JSON-LD context using an appropriate binding. Additionally, if a payload is defined in the initial request to the Context Broker, the “Content-Type” of the forwarded request shall be “application/json” and the Context Broker shall remove any @context members from the payload prior to distributing the request to the context source endpoint.

If the key “ngsildConformance”is defined:

The value shall define in the form major.minor, for example 1.5.
The Context Broker shall apply a backwards compatibility operation over the payload (as defined by clause 4.3.6.8) prior to distributing the request to the context source endpoint such that the forwarded payload conforms to the specified version of the NGSI-LD specification.

4.3.6.7 Querying and Retrieving Distributed Entities as Unitary Operations

Context Broker architectures assume that Entity data does not need to be centralized within a single Context Broker, however, when querying context information, Entity data retrieval can be considered as a unitary operation, masking the fact that each registered Context Broker is receiving a separate distributed Context Consumption request.

To process each Context Consumption request efficiently, and to support consistent pagination, it is necessary for the Context Broker to initially make a broad request to each registered Context Source whose registration is matching the request.

In the case of a query Entities operation (clause 5.7.2) or query Temporal Evolution of Entities operation (clause 5.7.4), a list of Entity identifiers is returned and stored together with the registration information in an Entity map. Only the Entities whose identifiers are contained in the Entity map are considered when rendering the result pages. Filtering based on queries, geoqueries, scope queries or attribute filters, as provided in the original query request, is applied to the Entities before adding the Entity to a result page, i.e. identifiers of Entities not matching the filters at the time of checking are removed from the Entity map.

In the case of a retrieve Entity operation (clause 5.7.1) or retrieve Temporal Evolution of an Entity operation (clause 5.7.3), an Entity map can be used to make subsequent retrievals of the same Entity more efficient, as the Entity map provides the information about which Context Source(s) store relevant Entity information, and other Context Sources do not have to be considered.

This Entity mapping is an internal operation, not usually exposed to the end user, however it is necessary to explicitly define a consistent mechanism for Entity map creation, caching and retrieval.

A specific field pointing to the location of a cached EntityMap (e.g. a custom header in the response in case of HTTP binding, see Table 6.4.3.2‑2) shall be returned within the response of a query, whenever this is requested by the client. Similarly, the reuse of a previously created EntityMap can be requested by passing the same specific field into a request.

Since an exclusive Context Source Registration already specifies that all context data is held in a single location, its relevance to a distributed query can be inferred within the Registered Context Source without the use of an EntityMap.

When executing Context Consumption or Subscription operations, a significant optimization in performance can be achieved if it is known a priori whether individual Entities are themselves distributed among Context Brokers and Context Sources, or if each Context Broker and Context Source always stores complete Entities. In the latter case all parameters used for filtering such as queries, geoqueries, scope queries or attribute filters can be forwarded and applied locally, whereas in the former case, the Entity first has to be assembled by the Context Broker and only then the filtering can be applied. Since being able to apply filters locally is significantly more efficient, a parameter can indicate that, for the given request, only Entities are to be expected that are stored in their entirety on each Context Broker and each Context Sources, and there are no Entities that are themselves stored in a distributed fashion. Such Entities are also referred to as split Entities. Context Broker implementations should enable configuring a default for this parameter, so deployments where no split Entities are to be expected can filter locally and thus be more efficient.

In the case of split Entities, EntityMaps initially only store “candidate Entities” as no filters could be applied, because only a part of the Entity was available. In the process of pagination, the filters will be (re-)checked. Any Entity not (or no longer) fulfilling the filter shall be removed from the EntityMap.

4.3.6.8 Backwards compatibility of Context Source payloads

When retrieving Entity data found distributed across multiple associated Context Brokers each Context Source is sent a context consumption request. A Context Broker shall assume that every Context Source will return valid NGSI-LD Entity data in a format that it understands and it shall reject data that is invalid. However, since the definition of a valid NGSI-LD Entity has broadened with each version of the NGSI-LD specification, it is possible that a registered Context Sourcecould respond with valid NGSI-LD Entity data which does not fit the narrower confines of a previous NGSI-LD specification.

Therefore, when making a context consumption request, a Context Broker may wish to indicate that it is only capable of interpreting responses which conform to a specific NGSI-LD specification, in which case the Context Sourceshall endeavour to amend its payload accordingly. Table 4.3.6.8‑1 describes a minimal level of support for a NGSI-LD Entity data as specified by each version of the NGSI-LD specification, and the expected fallback behaviour required if a context consumption request is made to receive data conformant to an earlier version of the NGSI-LD specification. Table 4.3.6.8‑2 describes conformance fallbacks for an NGSI-LD Property (and its subclasses) and Table 4.3.6.8‑2 describes conformance fallbacks for an NGSI-LD Relationship (and its subclasses).

The version of the NGSI-LD specification requested and the conformant version returned is defined in the form major.minor, for example 1.5.

Table 4.3.6.8-1: NGSI-LD Entity data type attribute support

Name	Data Type	Definition	Version Introduced	Conformant Data Fallback
id	String	Valid URI	1.0
type	String or String[] (see note 1)	1.0
expiresAt	String	DateTime as mandated by clause 4.22	1.9	Remove attribute from payload
location	GeoProperty	Default geospatial Property of an entity. See clause 4.7	1.0
observationSpace	GeoProperty	See clause 4.7	1.0
operationSpace	GeoProperty	See clause 4.7	1.0
scope	String or String[]	See clause 4.18	1.4	Remove attribute from payload
`<Property name>`	Property or Property[] (see note 2)	Property as mandated by clause 4.5.2.	1.0
	GeoProperty or GeoProperty[] (see note 2)	GeoProperty as mandated by clause 4.5.2.	1.0
	LanguageProperty or LanguageProperty[] (see note 2)	LanguageProperty as mandated by clause 4.5.18.	1.4	Reformat attribute as Property
	JsonProperty or JsonProperty[] (see note 2)	JsonProperty as mandated by clause 4.5.24.	1.8	Reformat attribute as Property
	VocabProperty or VocabProperty[] (see note 2)	VocabProperty as mandated by clause 4.5.20.	1.8	Reformat attribute as Property
	ListProperty or ListProperty[] (see note 1)	ListProperty as mandated by clause 4.5.21.	1.8	Reformat attribute as Property
`<Relationship name>`	Relationship or Relationship[] (see note 3)	Relationship as mandated by clause 4.5.3.	1.0
`<Relationship name>`	ListRelationship or ListRelationship[] (see note 3)	ListRelationship as mandated by clause 4.5.22.	1.8	Reformat attribute as Relationship
NOTE 1: From 1.3 onwards, an Entity type can be assigned multiple values. For 1.0 backwards compatibility only return a single element with preference to the first instance. NOTE 2: From 1.3 onwards, multiple instances of a Property (or subclass of Property ) identified by the same Property name can be separated by datasetId. For 1.0 backwards compatibility only return a single element of Property Array with preference to the default instance. NOTE 3: From 1.3 onwards, multiple instances of a Relationship (or subclass of Relationship ) identified by the same Relationship name can be separated by datasetId. From 1.3 onwards. For 1.0 backwards compatibility only return a single element of Relationship Array with preference to the default instance.

Table 4.3.6.8-2: NGSI-LD Property data type attribute support

Name	Data Type	Definition	Version Introduced	Conformant Data Fallback
type	String	1.0
value	Any JSON value as defined by IETF RFC 8259 [6]	See NGSI-LD Value definition in clause 3.1	1.0
datasetId	String	Valid URI as mandated by clause 4.5.5	1.3	Remove attribute from payload
expiresAt	String	DateTime as mandated by clause 4.22	1.9	Remove attribute from payload
observedAt	String	DateTime as mandated by clause 4.8	1.3	Remove attribute from payload
unitCode	String	As mandated by [15]	1.3	Remove attribute from payload
valueType	String	See clause 4.5.2	1.9	Remove attribute from payload

Table 4.3.6.8-3: NGSI-LD Relationship data type attribute support

Name	Data Type	Definition	Version Introduced	Conformant Data Fallback
type	String	Valid URI	1.0
object	String or String[]	1.0
datasetId	String	Valid URI as mandated by clause 4.5.5	1.3	Remove attribute from payload
expiresAt	String	DateTime as mandated by clause 4.22	1.9	Remove attribute from payload
objectType	String or String[]	See clause 4.5.23	1.8	Remove attribute from payload
observedAt	String	DateTime as mandated by clause 4.8	1.3	Remove attribute from payload

When responding to a context consumption request to supply data conforming to a specific NGSI-LD specification, Context Sources should indicate the version of the specification the returned payload actually conforms to. In general, Context Sources will not be expected to be flexible enough to supply payloads conformant to all past and future versions of the specification, but the requesting Context Broker may use supplied version information when collating data from multiple Context Sources. and to validate and amend received payloads.

4.3.7 Snapshots

Context information can be dynamic, e.g. when a query result contains many Entities, and the user has to paginate through the result set, the values encountered later may be from a much later point in time than earlier results, making them incomparable. To get more consistent results, the Snapshot concept is introduced, which can be optionally implemented by Context Brokers. It enables “freezing” the result by retrieving all results immediately and persisting them locally. Context Consumers can then query and analyse the Snapshot in a much more consistent way.

This is especially relevant for distributed cases, where information initially was distributed across multiple Context Brokers and Context Sources.

Snapshots offer the full functionality of NGSI-LD available locally and can be used as a basis for simulations that enable making predictions or “what-if” analyses, which are often needed for digital twins.

4.4 Core and user NGSI-LD @context

NGSI-LD serialization is based on JSON-LD [2], a JSON-based format to serialize Linked Data. The @context in JSON-LD is used to expand terms, provided as short-hand strings, to concepts, specified as URIs, and vice versa, to compact URIs into terms. The Core NGSI-LD (JSON-LD) @context is defined as a JSON-LD @context which contains:

The core terms needed to uniquely represent the key concepts defined by the NGSI-LD Information Model, as mandated by clause 4.2.
The terms needed to uniquely represent all the members that define the API-related Data Types, as mandated by clauses 5.2 and 5.3.
A fallback @vocab rule to expand or compact user-defined terms to a default URI, in case there is no other possible expansion or compaction as per the current @context.
The core NGSI-LD @context defines the term “id”, which is mapped to @id, and the term “type”, which is mapped to @type. Since @id and @type are what is typically used in JSON-LD, they may also be used in NGSI-LD requests instead of “id” and “type”respectively, wherever this is applicable. In NGSI-LD responses, only “id” and “type” shall be used.

NGSI-LD compliant implementations shall support such Core @context, which shall be implicitly present when processing or generating context information. Furthermore, the Core @context is protected and shall remain immutable and invariant during expansion or compaction of terms. Therefore, and as per the JSON-LD processing rules [2], when processing NGSI-LD content, implementations shall consider the Core @context as if it were in the last position of the @context array. Nonetheless, for the sake of compatibility and cleanness, data providers should generate JSON-LD content that conveys the Core @context in the last position.

For the avoidance of doubt, when rendering NGSI-LD Elements, the Core @context shall always be treated as if it had been originally placed in the last position, so that, if needed, upstream JSON-LD processors can properly expand as NGSI-LD or override the resulting JSON-LD documents provided by API implementations.

The NGSI-LD Core @context is publicly available at <https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld> and shall contain all the terms as mandated by annex B.

In addition to the terms defined by the Core NGSI-LD @context (mandatory as per annex B), a user @context should be provided and it should contain the following terms:

One term associated to the Entity Type, mapping the Entity Type name with its Type Identifier (URI).
One term associated to the name of each Property or any of its subclasses mapping the Property name with its Property Identifier (URI). If the Property’s range is a data type different than a native JSON type, then it shall be conveyed explicitly under this term by using a nested JSON object in the form:

“@type”: <Datatype's URI>.
“@id”: <Property's URI>.

One term associated to the name of each Relationship mapping the Relationship name with the Relationship Identifier (URI) in the form:

“@type”:“@id” .
“@id”: <Relationship's URI>.

Whereas the Core NGSI-LD @context contains JSON-LD Scoped Contexts, the user @context shall not contain JSON-LD Scoped Contexts (see [2], ), as described in clause 5.5.7, because this would enable overwriting terms defined in the Core NGSI-LD @context.

Depending on the binding, the @context may not just be provided embedded with the rest of the JSON content, but there could be other options. For example, in the HTTP binding, the @context can be made available through a Link header (see clause 6.3.5).

4.5 NGSI-LD Data Representation

4.5.0 Introduction

All NGSI-LD elements are represented in JSON-LD [2]. For the use with the API, the compacted JSON-LD representation is used, i.e. short terms are used, which are expanded by the component implementing the NGSI-LD API using a JSON-LD @context, typically provided as part of the request. As described in clause 4.4, the NGSI-LD Core @context is always considered to be part of the @context to be used.

The use of JSON-LD for NGSI-LD elements has some implications for the use of null values, as JSON-LD interprets setting elements to null as elements to be removed when performing JSON-LD expansion. Thus, null cannot be used as a value in NGSI-LD.

To nevertheless allow deletions as part of NGSI-LD operations that update NGSI-LD data, which is typically handled by setting the respective JSON key to null (e.g. as in IETF RFC 7396 [16]), the URI “urn:ngsi-ld:null” is used as a replacement for null in all places where URI strings are valid JSON values. If an array is required, an array with one single NGSI-LD Null is used. For languageMap, the JSON object {“@none”: “urn:ngsi-ld:null”} is to be used as explained in clause 4.5.18. These encodings of null are referred to as NGSI-LD Null.

For representing deleted elements in notifications and in the temporal representation, the URI “urn:ngsi-ld:null” is used as a Property value or Relationship object and the JSON object {“@none”: “urn:ngsi-ld:null”} for the “languageMap” of a Language Property, respectively.

As null cannot be used as a value in JSON-LD, there is still the possibility of using a JSON null literal represented as {“@type”: “@json”, “@value”: null} in JSON-LD instead. JSON literals are not to be expanded in JSON-LD and thus the respective element is not removed during JSON-LD expansion.

4.5.1 NGSI-LD Entity Representation

An NGSI-LD Entity shall be represented by an object encoded using JSON-LD [2]. The rules described below state the encoding that shall be supported by implementations. Annex D provides a computational description of this process in terms of an algorithm.

The JSON-LD object contains the following members:

Mandatory

“id” whose value shall be a URI that identifies the Entity.
“type” whose value shall be equal to the Entity Type name or an unordered JSON array with multiple Entity Type names in case of an Entity that has multiple Entity Types.

Optional

“expiresAt”: a string as mandated by clause 4.22.
“scope” whose value shall be a Scope as defined in clause 4.18 or an unordered JSON array with multiple Scopes in case of an Entity that has multiple Scopes.
“@context” a JSON-LD @context as described in clause 4.4.
One member for each Property as per the rules stated in clause 4.5.2. In case of multiple Property instances with the same Property name as described in clause 4.5.5, all instances are provided as an unordered JSON array, and datasetId (see clause 4.5.5) shall be used to distinguish them.
One member for each Relationship as per the rules stated in clause 4.5.3. In case of multiple Relationship instances with the same Relationship name as described in clause 4.5.5, all instances are provided as an unordered JSON array, and datasetId (see clause 4.5.5) shall be used to distinguish them.

NOTE 1:

In the following, the term Attribute is used when referring in the text to both a Property and a Relationship (see definition of NGSI-LD Attribute in clause 3.1 ).

NOTE 2:

When GeoJSON representation is selected, the layout of the Entities changes, see clause 4.5.16 for details.

Terms defined in the Core Context as non-reified Properties (such as “datasetId”, “instanceId”, etc.) shall not be used as Attribute names.

Attributes shall not contain any embedded @context, as described in clause 5.5.7.

4.5.2 NGSI-LD Property Representations

4.5.2.1 Introduction

An NGSI-LD Property, its value and sub-attributes can be represented in two equally valid lossless formats. The normalized representation is a JSON-LD document that is complete with respect to mandatory members. The concise representation is a terser alternative, which makes various implicit assumptions against the payloads and removes redundancy from them.

Both normalized and concise representation of Properties shall be supported by implementations and can be selected by Context Consumers through specific request parameters. An example of this representation can be found in annex C, clause C.2.2.

4.5.2.2 Normalized NGSI-LD Property

An NGSI-LD Property in normalized representation shall be represented by a member whose key is the Property name (a term) and whose value is a JSON-LD object (or JSON-LD array with such JSON-LD objects, if there are multiple instances with the same Property name, as described in clause 4.5.5), which includes the following members:

Mandatory

“type”: the fixed value “Property”.
“value”: the Property Value (see definition of NGSI-LD Value in clause 3.1). The datatype URI can be placed in the optional “valueType” member.

An NGSI-LD Null (explained in clause 4.5.0 and defined in clause 3.1) can be used as the right-hand side of the “value” during partial update patch and merge patch (see clauses 5.5.8 and 5.5.12) to indicate a deletion of the Property, as well as in notifications and in temporal evolutions (for encoding a deleted Property).

It should be noted that in the JSON-LD serialization, a number data type does not allow for leading zeros, and octal and hexadecimal formats are not used. In the context broker’s internal representation, a number is equivalent to either an integer or floating-point number, depending on if the number has a non-zero fractional part. The degree of precision of a floating-point number held within a context broker will depend upon the implementation, and insignificant digits may be lost during the deserialization and serialization process.

Optional

“datasetId”: a URI as mandated by clause 4.5.5.
“expiresAt”: a string as mandated by clause 4.22.
“ngsildproof”: a Property with the non-reified subproperties “entityIdSealed” and “entityTypeSealed”as specified in [35]. The value of its “value” element shall be an object containing the W3C^® Data integrity “proof” structure [35]. See clause C.11 for an example.
“observedAt”: a string as mandated by clause 4.8.
“unitCode”: a string representing the measurement unit corresponding to the Property value. It shall be encoded using the UNECE/CEFACT Common Codes for Units of Measurement [15].
“valueType”: a string value which shall be type coerced into a datatype URI. It is a non-reified alternative to the use of a native JSON-LD @type for the Property value. When it is a JSON primitive, it should align this with the RDF datatype [34].
For each of the Properties this Property is associated with, a member whose key (a term) is the Property name and value is the result of serializing a Property (or any of its subclasses) in normalized representation (see clause 4.5.2.2).
For each of the Relationships this Property is associated with, a member whose key (a term) is the Relationship name and value is the result of serializing a Relationship in normalized representation (see clause 4.5.3.2).

System Generated

“createdAt”: a string as mandated by clause 4.8.
“deletedAt”: a string as mandated by clause 4.8.
“instanceId”: a URI uniquely identifying a Property instance, as mandated by clause 4.5.7.
“modifiedAt”: a string as mandated by clause 4.8.

Output Only

“previousValue”: only provided only in the case of notifications and only if the showChanges option is explicitly requested. It represents the previous Property Value, before the triggering change. The representation is the same as that of “value”.

Furthermore, an NGSI-LD Property in the normalized representation shall never include the following members:

Prohibited

“entity”: shall never be present, as it is used during inline Linked Entity retrieval to define the target Entity of a Relationship’s object.
“entityIdSealed”and“entityTypeSealed”: shall never be present, unless the Property name is “ngsildproof”.
“entityList”: shall never be present, as it is used during inline Linked Entity retrieval to define the target Entities of a ListRelationship’s object.
“json” and “previousJson”: shall never be present, as they define a JsonProperty value.
“languageMap” and “previousLanguageMap”: shall never be present, as they define a LanguageProperty value.
“object” and “previousObject”: shall never be present, as they define a Relationship’s object URI.
“objectList” and “previousObjectList”: shall never be present, as they define an ordered array of Relationship object URIs.
“valueList” and “previousValueList”: shall never be present, as they define an ordered array of Property values.
“vocab” and “previousVocab”: shall never be present, as they define a VocabProperty value.

4.5.2.3 Concise NGSI-LD Property

An NGSI-LD Property without sub-attributes shall be represented in a concise but lossless representation by a member whose key is the Property name (a term) and whose value is the Property Value (see definition of NGSI-LD Value in clause 3.1). In this case the concise representation is equivalent to simplified representation (see clause 4.5.4). If the provided value is a JSON object and contains a “type” field, the whole Attribute shall be treated as a normalized representation (see clause 4.5.2.2).

An NGSI-LD Property which includes sub-attributes shall be represented in a concise but lossless representation by a member whose key is the Property name (a term) and whose value is a JSON-LD object (or JSON-LD array with such JSON-LD objects if there are multiple instances with the same Property name as described in clause 4.5.5) which includes the following members:

Mandatory

“value”: the Property Value (see definition of NGSI-LD Value in clause 3.1). The datatype URI can be placed in the optional “valueType” member. An NGSI-LD Null (explained in clause 4.5.0 and defined in clause 3.1) can be used as the right-hand side of the “value” during partial update patch and merge patch (see clauses 5.5.8 and 5.5.12) to indicate a deletion of the Property, as well as in notifications and in temporal evolutions (for encoding a deleted Property).

Optional

“datasetId”: a URI as mandated by clause 4.5.5.
“expiresAt”: a string as mandated by clause 4.22.
“ngsildproof”: a Property with the non-reified subproperties “entityIdSealed” and “entityTypeSealed”as specified in [35]. The value of its “value” element shall be an object containing the W3C^®Data integrity “proof” structure [35]. See clause C.11 for an example.
“observedAt”: a string as mandated by clause 4.8.
“type”: If missing, “Property” can be inferred by the presence of the “value” attribute. An exception to this inference rule occurs for geospatial Property Values, where the “GeoProperty” sub-type shall be inferred instead, if the Property Value resolves to a supported GeoJSON geometry (see clause 4.7).
“unitCode”: a string representing the measurement unit corresponding to the Property value. It shall be encoded using the UNECE/CEFACT Common Codes for Units of Measurement [15].
“valueType”: a string value which shall be type coerced into a datatype URI. It is a non-reified alternative to the use of a native JSON-LD @type for the Property value. When it is a JSON primitive, it should align this with the RDF datatype [34].
For each of the Properties this Property is associated with, a member whose key (a term) is the Property name and value is the result of serializing a Property (or any of its subclasses) in concise representation (see clause 4.5.2.3).
For each of the Relationships this Property is associated with, a member whose key (a term) is the Relationship name and value is the result of serializing a Relationship (or any of its subclasses) in concise representation (see clause 4.5.3.3).

System Generated

“createdAt”: a string as mandated by clause 4.8.
“deletedAt”: a string as mandated by clause 4.8.
“instanceId”: a URI uniquely identifying a Property instance as mandated by clause 4.5.7.
“modifiedAt”: a string as mandated by clause 4.8.

Output Only

“previousValue”: only provided if the showChanges option is explicitly requested. It represents the previous Property Value, before the triggering change. The representation is the same as that of “value”.

Furthermore, an NGSI-LD Property in the concise representation shall never include the following members:

Prohibited

“entity”: shall never be present, as it is used during inline Linked Entity retrieval to define the target Entity of a Relationship’s object.
“entityIdSealed”and“entityTypeSealed”shall never be present, unless the Property name is “ngsildproof”.
“entityList”: shall never be present, as it is used during inline Linked Entity retrieval to define the target Entities of a ListRelationship’s object.
“languageMap” and “previousLanguageMap”: shall never be present, as they define a LanguageProperty value.
“json” and “previousJson”: shall never be present, as they define a JsonProperty value.
“object” and “previousObject”: shall never be present, as they define a Relationship’s object URI.
“objectList” and “previousObjectList”: shall never be present, as they define an ordered array of Relationship object URIs.
“vocab” and “previousVocab”: shall never be present, as they define a VocabProperty value.
“valueList” and “previousValueList”: shall never be present, as they define an ordered array of Property values.

4.5.3 NGSI-LD Relationship Representations

4.5.3.1 Introduction

An NGSI-LD Relationship, its value and sub-attributes can be represented in two equally valid lossless formats. The normalized representation is a JSON-LD document that is complete with respect to mandatory members. The concise representation is a terser alternative, which makes various implicit assumptions against the payloads and removes redundancy from them.

Both normalized and concise representation of Relationships shall be supported by implementations and can be selected by Context Consumers through specific request parameters. An example of this representation can be found in annex C, clause C.2.2.

4.5.3.2 Normalized NGSI-LD Relationship

An NGSI-LD Relationship in normalized representation shall be represented by a member whose key is the Relationship name (a term) and whose value is a JSON-LD object (or JSON-LD array with such JSON-LD objects, if there are multiple instances with the same Relationship name, as described in clause 4.5.5) with the following terms:

Mandatory

“object”: the Relationship’s object represented by a URI or array of URIs. An NGSI-LD Null (explained in clause 4.5.0 and defined in clause 3.1) can be used as the right-hand side of the “object” during partial update patch and merge patch (see clauses 5.5.8 and 5.5.12) to indicate a deletion of the Relationship, as well as in notifications and in temporal evolutions (for encoding a deleted Relationship).
“type”: the fixed value “Relationship”.

Optional

“datasetId”: a URI as mandated by clause 4.5.5.
“expiresAt”: a string as mandated by clause 4.22.
“ngsildproof”: a Property, as mandated by clause 4.5.2, with the non-reified subproperties “entityIdSealed” and “entityTypeSealed”as specified in [35]. The value of its “value” element shall be an object containing the W3C^®Data integrity “proof” structure [35]. See clause C.11 for an example.
“objectType”: a string as mandated by clause 4.5.23.
“observedAt”: a string as mandated by clause 4.8.
For each Relationship this Relationship is associated with, a member whose key is the Relationship name (a term) and whose value is the result of serializing a Relationship (or any of its subclasses) as per the rules of representation of a Relationship in normalized representation (see clause 4.5.3.2).
For each Property this Relationship is associated with, a member whose key is the Property name (a term) and whose value is the result of serializing a Property (or any of its subclasses) as per the rules of representation of a Property in normalized representation (see clause 4.5.2.2).

System Generated

“createdAt”: a string as mandated by clause 4.8.
“deletedAt”: a string as mandated by clause 4.8.
“instanceId”: a URI uniquely identifying a Relationship instance as mandated by clause 4.5.8.
“modifiedAt”: a string as mandated by clause 4.8.

Output Only

“entity”: only provided in case of Linked Entity retrieval, and only if the inline join option is explicitly requested (see clause 4.5.23.2), where it used to define the target Linked Entity of a Relationship’s object in normalized representation.
“previousObject”: only provided if the showChanges option is explicitly requested. It represents the previous Relationship “object”, before the triggering change. The representation is the same as that of “object”.

Furthermore, an NGSI-LD Relationship in the normalized representation shall never include the following members:

Prohibited

“entityIdSealed”and“entityTypeSealed”shall never be present.
“entityList” shall never be present, as it is used during inline Linked Entity retrieval to define the target Entities of a ListRelationship’s object.
“languageMap” and“previousLanguageMap”:shall never be present, as they define a LanguageProperty value.
“json” and “previousJson”: shall never be present, as they define a JsonProperty value.
“objectList” and “previousObjectList”: shall never be present, as they define an ordered array of Relationship object URIs.
“unitCode”: shall never be present, as Relationships are unitless.
“value” and “previousValue”: shall never be present, as they define a Property value.
“valueList” and “previousValueList”: shall never be present, as they define an ordered array of Property values.
“vocab” and “previousVocab”: shall never be present, as they define a VocabProperty value.

4.5.3.3 Concise NGSI-LD Relationship

An NGSI-LD Relationship in shall be represented in a concise but lossless representation by a member whose key is the Relationship name (a term) and whose value is a JSON-LD object (or JSON-LD array with such JSON-LD objects if there are multiple instances with the same Relationship name as described in clause 4.5.5) with the following terms:

Mandatory

“object”: the Relationship’s object represented by a URI or array of URIs. An NGSI-LD Null (explained in clause 4.5.0 and defined in clause 3.1) can be used as the right-hand side of the “object” during partial update patch and merge patch (see clauses 5.5.8 and 5.5.12) to indicate a deletion of the Relationship, as well as in notifications and in temporal evolutions (for encoding a deleted Relationship).

Optional

“datasetId”: a URI as mandated by clause 4.5.5.
“expiresAt”: a string as mandated by clause 4.22.
“ngsildproof”: a Property, as mandated by clause 4.5.2, with the non-reified subproperties “entityIdSealed” and “entityTypeSealed”as specified in [35]. The value of its “value” element shall be an object containing the W3C^®Data integrity “proof” structure [35]. See clause C.11 for an example.
“observedAt”: a string as mandated by clause 4.8.
“objectType”: a string as mandated by clause 4.5.23.
“type”: If missing, “Relationship” can be inferred by the presence of the “object” attribute.
For each Relationship this Relationship is associated with, a member whose key is the Relationship name (a term) and whose value is the result of serializing a Relationship (or any of its subclasses) as per the rules of representation of a Relationship in concise representation. (see clause 4.5.3.3).
For each Property this Relationship is associated with, a member whose key is the Property name (a term) and whose value is the result of serializing a Property (or any of its subclasses) as per the rules of representation of a Property in concise representation. (see clause 4.5.2.3).

System Generated

“createdAt”: a string as mandated by clause 4.8.
“deletedAt”: a string as mandated by clause 4.8.
“instanceId”: a URI uniquely identifying a Relationship instance as mandated by clause 4.5.8.
“modifiedAt”: a string as mandated by clause 4.8.

Output Only

“entity”: only provided in case of Linked Entity retrieval, and only if the inline join option is explicitly requested (see clause 4.5.23.2), where it used to define the target Linked Entity of a Relationship’s object in concise representation.
“previousObject”: only provided if the showChanges option is explicitly requested. It represents the previous Relationship “object”, before the triggering change. The representation is the same as that of “object”.

Furthermore, an NGSI-LD Relationship in the concise representation shall never include the following members:

Prohibited

“entityIdSealed”and“entityTypeSealed”shall never be present.
“entityList”: shall never be present, as it is used during inline Linked Entity retrieval (see clause 4.5.23.2) to define the target Entities of a ListRelationship’s object.
“languageMap” and “previousLanguageMap”: shall never be present, as they define a LanguageProperty value.
“json” and “previousJson”: shall never be present, as they define a JsonProperty value.
“objectList” and “previousObjectList”: shall never be present, as they define an ordered array of Relationship object URIs.
“unitCode”: shall never be present, as Relationships are unitless.
“valueList” and “previousValueList”: shall never be present, as they define an ordered array of Property values.
“value” and “previousValue”: shall never be present, as they define a Property value.
“vocab” and “previousVocab”: shall never be present, as they define a VocabProperty value.

Notwithstanding the definition above, during partial update patch and merge patch (see clauses 5.5.8 and 5.5.12), an NGSI-LD Relationship with a value of NGSI-LD Null and without a datasetId should be represented in a concise representation by a member whose key is the Relationship name (a term) and whose value is “urn:ngsi-ld:null”.

4.5.4 Simplified Representation

The NGSI-LD specification defines an abbreviated, lossy representation of Entities, which allows consuming only entity data (the target object of each Relationship or the value of each Property) corresponding to the Properties or Relationships whose subject is the Entity itself i.e. the own Attributes of the Entity. The simplified representation of Entities shall be supported by implementations and can be selected by Context Consumers through specific request parameters. An example of this representation can be found in annex C, clause C.2.2.

The simplified representation of an Entity shall be a JSON-LD object containing the following members:

Mandatory

“id” whose value shall be a URI that identifies the Entity.
“type” whose value shall be equal to the Entity Type name or an unordered JSON array with multiple Entity Type names in case of an Entity that has multiple Entity Types.

Optional

“@context”, a JSON-LD @context as described in clause 4.4.
For each Property a member whose key is the Property name (a term) and whose value is the Property Value.

EXAMPLE 1:

“name”: “David Robert Jones”

In the multi-attribute case (see clause 4.5.5), the simplified representation of a Property (or any of its subtypes) changes. Each Property consists of a key-value pair, the key being the Property name (a term) and the value being a JSON Object, which contains a single Attribute with a key called “dataset”, and its value in turn is a JSON Object holding a series of key-value pairs, one for each datasetId, where the value corresponds to the simplified representation of the property value. The default datasetId (where present) is represented by the JSON-LD keyword “@none”.

EXAMPLE 2:

"name": {
  "dataset": {
    "@none": "David Robert Jones",
    "urn:ngsi-ld:datasetId:001": "David Bowie",
    "urn:ngsi-ld:datasetId:002": "Ziggy Stardust"
  }
}

For each GeoProperty, a member whose key is the Property name (a term) and whose value is the Property Value.

EXAMPLE 3:

“location”: {“type”: “Point”, “coordinates”: [13.3986, 52.5547]}

For each LanguageProperty, a member whose key is the Property name (a term) and whose value is a JSON Object containing a single Attribute with a key called “languageMap” where the value shall correspond to a LanguageProperty languageMap.

EXAMPLE 4:

“says”: {“languageMap”: {“en”: “yes”, “fr”: “oui”}

For each JsonProperty, a member whose key is the Property name (a term) and whose value is a JSON Object containing a single Attribute with a key called “json” where the value shall correspond to the raw JSON data that cannot be held in JSON-LD format. Within the example below, the id attribute is never expanded to @id and therefore does not have to be defined as a URI, and the value attribute is never expanded to ngsi-ld:hasValue.

EXAMPLE 5:

"parkingTickets": {
  "json": {
     "id": "85a6cc52-0589-45f9",
     "value": "Overstay 60 minutes"
  }
}

For each VocabProperty, a member whose key is the Property name (a term) and whose value is a JSON Object containing a single Attribute with a key called “vocab” where the value shall correspond to a VocabProperty vocab.

EXAMPLE 6:

“gender”: {“vocab”: “Male”}

For each Relationship a term whose key is the Relationship name (a term) and whose value is the Relationship’s Object (represented as a URI or array of URIs).

EXAMPLE 7:

” providedBy”: “urn:ngsi-ld:Device:31415”

EXAMPLE 8:

"devices": [
     "urn:ngsi-ld:Device:14142",
     "urn:ngsi-ld:Device:13562", 
     "urn:ngsi-ld:Device:37309"
]

In the inline Linked Entity retrieval case (see clause 4.5.23.2), the simplified representation of a Relationship changes. Any Relationship which targets an Entity stored locally or includes an objectType Attribute is returned as a JSON object holding key-value pairs corresponding to the data from the Relationship’s object URI in simplified format.

EXAMPLE 9:

"providedBy": {
  "id": "urn:ngsi-ld:Device:31415",
  "type": "Device",
  "brandName": "Anemometer",
  "manufacturerName": "Cyberdyne Systems",
  "windSpeed": 60
}

EXAMPLE 10:

"devices": [
    {
       "id": "urn:ngsi-ld:Device:14142",
       "type": "Device",
       "brandName": "Anemometer",
       "manufacturerName": "Cyberdyne Systems",
        "windSpeed": 60
    },
    {
       "id": "urn:ngsi-ld:Device:13562",
       "type": "Device",
       "brandName": "Hygromometer",
       "manufacturerName": "Acme Corporation",
       "humidity": 64
    },
    { 
       "id": "urn:ngsi-ld:Device:37309",
       "type": "Device",
       "brandName": "Barometer",
       "manufacturerName": "Trask Industries",
       "pressure": 760
    }
]

In the flattened Linked Entity retrieval case (see clause 4.5.23.3), the simplified representation of a Relationship changes to return multiple Entities. Any Relationships which target Entities stored locally or include an objectType Attribute are returned as part of the array as an additional JSON object holding key-value pairs corresponding to the data from the Relationship’s object URI in simplified format.

EXAMPLE 11:

[
  {
    …etc
    "providedBy": "urn:ngsi-ld:Device:31415"
  },
  {
    "id": "urn:ngsi-ld:Device:31415",
    "type": "Device",
    "brandName": "Anemometer",
    "manufacturerName": "Cyberdyne Systems",
    "windSpeed": 60
  }
]

EXAMPLE 12:

[
    {
      … etc
      "providedBy": [
       "urn:ngsi-ld:Device:14142", 
         "urn:ngsi-ld:Device:13562", 
         "urn:ngsi-ld:Device:37309"
       ]
    },
    {
       "id": "urn:ngsi-ld:Device:14142",
       "type": "Device",
       "brandName": "Anemometer",
       "manufacturerName": "Cyberdyne Systems",
       "windSpeed": 60
    },
    {
       "id": "urn:ngsi-ld:Device:13562",
       "type": "Device",
       "brandName": "Hygromometer",
       "manufacturerName": "Acme Corporation",
       "humidity": 64
    },
    {
       "id": "urn:ngsi-ld:Device:37309",
       "type": "Device",
       "brandName": "Barometer",
       "manufacturerName": "Trask Industries",
       "pressure": 760
    }
]

In the multi-attribute case (see clause 4.5.5), the simplified representation of a Relationship changes. Each Relationship consists of a key-value pair, the key being the Relationship name (a term) and the value being a JSON Object containing a single Attribute with a key called “dataset” and its value in turn is a JSON Object holding a series of key-value pairs, one for each datasetId, where the value corresponds to the object of the Relationship. The default datasetId (where present) is represented by the JSON-LD keyword “@none”.

EXAMPLE 13:

"providedBy": {
  "dataset": {
    "@none": "urn:ngsi-ld:Device:31415",
    "urn:ngsi-ld:datasetId:001": "urn:ngsi-ld:Device:27182",
    "urn:ngsi-ld:datasetId:002": "urn:ngsi-ld:Device:14142"
  }
}

For each ListProperty a member whose key is the Property name (a term) and whose value is an ordered array holding the Property Values.

EXAMPLE 14:

“periods”: [“First”, “Second”, “Third”, “Fourth”]

In the multi-attribute case (see clause 4.5.5), the simplified representation of a ListProperty changes. Each ListProperty consists of a key-value pair, the key being the Property name (a term) and the value being a JSON Object containing a single Attribute with a key called “dataset” and its value in turn is a JSON Object holding a series of key-value pairs, one for each datasetId, where the value corresponds to the simplified representation of the ListProperty valueList. The default datasetId (where present) is represented by the JSON-LD keyword “@none”.

EXAMPLE 15:

"periods": {
  "dataset": {
    "@none": ["First", "Second", "Third", "Fourth"],
    "urn:ngsi-ld:datasetId:001": ["1st", "2nd", "3rd", "4th"],
    "urn:ngsi-ld:datasetId:002": ["Primary", "Secondary", "Tertiary", "Quaternary"]
  }
}

For each ListRelationship a term whose key is the Relationship name (a term) and whose value is an ordered array holding the ListRelationship’s Objects (represented as URIs).

EXAMPLE 16:

"route":[
  "urn:ngsi-ld:BusStop:0101",
  "urn:ngsi-ld:BusStop:0102",
  "urn:ngsi-ld:BusStop:9912"
]

In the inline Linked Entity retrieval case (see clause 4.5.23.2), the simplified representation of a ListRelationship changes. Any ListRelationship which targets Entities stored locally or includes an objectType Attribute is returned as an ordered array of JSON objects holding key-value pairs corresponding to the data from the ListRelationship’s target objectList URIs in simplified format.

EXAMPLE 17:

"route": [
  {
    "id": "urn:ngsi-ld: BusStop:0101",
    "type": "BusStop",
    "stopName": "High Street",
    "location": {"type": Point, coordinates [54.112,0.334]}}
  },
  {
    "id": "urn:ngsi-ld: BusStop:0102",
    "type": "BusStop",
    "stopName": "Station Road", 
    "location": {"type": Point, coordinates [54.101,0.302]}}
  },
  {
    "id": "urn:ngsi-ld: BusStop:9912",
    "type": "BusStop",
    "stopName": "Mornington Cresent", 
    "location": {"type": Point, coordinates [54.142,0.332]}
  }
]

In the flattened Linked Entity retrieval case (see clause 4.5.23.3), the simplified representation of a ListRelationship changes to return multiple Entities. Any ListRelationships which target Entities stored locally or include an objectType Attribute are returned as additional JSON objects holding key-value pairs corresponding to the data from the ListRelationship’s target objectList URIs in simplified format.

EXAMPLE 18:

[
  {
    …etc
    "route": [
      "urn:ngsi-ld:BusStop:0101",
      "urn:ngsi-ld:BusStop:0102",
      "urn:ngsi-ld:BusStop:9912"
    ]
  },
  {
    "id": "urn:ngsi-ld: BusStop:0101"
    "type": "BusStop",
    "stopName": "High Street", 
    "location: {"type": "Point", "coordinates": [54.112,0.334]}}
  {
    "id": "urn:ngsi-ld: BusStop:0102",
    "type": "BusStop",
    "stopName": "Station Road", 
    "location": {"type": "Point", "coordinates": [54.101,0.302]}}
  },
  {
    "id": "urn:ngsi-ld:BusStop:9912"
    "type": "BusStop",
    "stopName": "Mornington Cresent", 
    "location: {"type": "Point", "coordinates": [54.142,0.332]}
  }
]

In the multi-attribute case (see clause 4.5.5), the simplified representation of a ListRelationship changes. Each ListRelationship consists of a key-value pair, the key being the Relationship name (a term) and the value being a JSON Object containing a single Attribute with a key called “dataset” and its value in turn is a JSON Object holding a series of key-value pairs, one for each datasetId, where the value corresponds to the array of objects of the relationship list. The default datasetId (where present) is represented by the JSON-LD keyword “@none”.

EXAMPLE 19:

"route": {
  "dataset": {
    "@none": [
      "urn:ngsi-ld:BusStop:0101",
      "urn:ngsi-ld:BusStop:0102",
      "urn:ngsi-ld:BusStop:9912"
     ],
     "urn:ngsi-ld:datasetId:001": [
       "urn:ngsi-ld:BusStop:0101",
       "urn:ngsi-ld:BusStop:0102",
       "urn:ngsi-ld:BusStop:0022"
     ],
     "urn:ngsi-ld:datasetId:002": [
       "urn:ngsi-ld:BusStop:0101",
       "urn:ngsi-ld:BusStop:0102",
       "urn:ngsi-ld:BusStop:0022",
       "urn:ngsi-ld:BusStop:9912"
    ]
  }
}

NOTE:

When the simplified GeoJSON representation is selected, the layout of the Entities changes, see clause 4.5.17 for details.

4.5.5 Multi-Attribute Support

4.5.5.1 Introduction

For each Entity, there can be Attributes that simultaneously have more than one instance. In the case of Properties, there may be more than one source at a time that provides a Property instance, e.g. based on independent sensor measurements with different quality characteristics. For instance, take a speedometer and a GPS both providing the current speed of a car. In the case of Relationships, there may be non-functional Relationships requiring separate metadata attached to each object, e.g. for a room, there may be multiple “contains” Relationships to all sorts of objects currently in the room that have been put there by different people (a separate “placedBy”Relationship-of-the-Relationship) and which are dynamically changing over time.

To be able to explicitly manage such multi-attributes, the optional datasetId property is used, which is of datatype URI, or equal to the JSON-LD keyword “@none”. It is introduced for Properties and Relationships in clauses 4.5.2 and 4.5.3 respectively. If a datasetId is provided when creating, updating, appending or deleting Attributes, only instances with the same datasetId are affected, leaving instances with another datasetId or an instance without a datasetId untouched. If no datasetId is provided, or “datasetId”: “@none” is supplied, it is considered as the default Attribute instance. Thus, the creation, updating, appending or deleting of Attributes without providing a datasetId only affects the default Attribute instance. There can only be one default Attribute instance for an Attribute with a given Attribute name in any request or response. An example can be found in annex C, clause C.2.2.

When requesting Entity information, if there are multiple instances of matching Attributes these are returned as arrays of Attributes, instead of a single Attribute element. The datasetId of the default Attribute instance is never explicitly included in responses, i.e. a default Attribute instance does not have a datasetId.

The datasetId can be used to create different “views” of Entities. All Attribute instances sharing the same datasetIdcan be seen as one “view”. If one or more datasetIds are specified in the request, only the Attribute instances that match one of the datasetIds will be returned. The datasetId of the default Attribute instance can be specified as “@none” In case that no Attribute instances match the provided datasetIds, then the Attribute shall not be returned with the Entity. If no datasetId is provided, then all available Attribute instances will be returned.

There is no multi-attribute support for non-reified Attributes, in particular this applies to the Temporal Properties createdAt, modifiedAt, deletedAt, expiresAt and observedAt, and also the unitCode Property.

4.5.5.2 Processing of Conflicting Transient Entities

In case of conflicting information when an Entity is received from a registered Context Sourceand marked with an expiresAt DateTime, but this expiresAt is not duplicated across all versions of the Entity received across all registered Context Sources, the following mechanism shall be used to differentiate.

For each version of the Entity received where the expiresAt non-reified attribute is present at the Entity level:

If no expiresAt attribute is present as a property of an Attribute, a non-reified expiresAt attribute is added as a property of that Attribute corresponding to the expiresAt found on the Entity.
If the expiresAt attribute is present as a property of an Attribute, and the value on the Attribute is further in the future than the expiresAt value found on the Entity, the value of the expiresAt on the Attribute is overwritten to corresponding to the earlier DateTime.

4.5.5.3 Processing of Conflicting Attributes

In case of conflicting information for an Attribute, where a datasetId is duplicated, but there are differences in the other attribute data, if an expiresAt DateTime is present on the Attribute and the date lies in the past, it shall be discarded, thereafter the one with the most recent observedAt DateTime, if present, and otherwise the one with the most recent modifiedAt DateTime shall be provided. If no other mechanism for determining the most current Attribute instance is found, the NGSI-LD system shall choose the Attribute instance at random and the result is indeterminate.

When conflicting information is received for the non-reified expiresAt attribute at an Entity level:

If an expiresAt attribute is missing from at least one version of the Entity received from registered Context Sources, the expiresAt attribute is removed from the Entity.
Otherwise, the expiresAt attribute of the Entity is set to the DateTime corresponding to the expiresAt DateTime which is furthest in the future.

4.5.6 Temporal Representation of an Entity

The temporal representation of an Entity is the way to represent the Temporal Evolution of an Entity: the Entity shall be as mandated by clause 4.5.1, but for each Property and Relationship their temporal representation shall be provided as mandated by clauses 4.5.7 and 4.5.8 and the Scope (if present) shall be represented as a temporal representation of a Property (clause 4.5.7) that can only have the non-reified Temporal Properties createdAt, modifiedAt, deletedAt and observedAt as sub-Properties. This is required to represent the Scope of a Temporal Evolution of an Entity. In case the Temporal Evolution of the Scope is updated as the result of a change from the Core API, the observedAt sub-Property should be set as a copy of the modifiedAt sub-Property.

4.5.7 Temporal Representation of a Property

The temporal evolution of a Property (for instance, its historical evolution or future predictions) is composed of the sequence of instances of the referred Property during a period of time within its lifetime.

The temporal representation of a Property shall be provided as an Array of JSON-LD objects (or a single JSON-LD object in case only one is present), each one representing an instance of the Property (as mandated by clause 4.5.2) at a particular point in time, which is recorded as a Temporal Property of the instance (typically observedAt). See example in annex C, clause C.5.6. In case the Property is deleted, an instance of the Property is recorded with its value set to the URI “urn:ngsi-ld:null” and the deletedAt Temporal Property set.

Systems should maintain an instanceId for each such Property instance. Without such an instanceId, it is not possible to selectively modify or delete temporal information via the NGSI-LD API. The consequences of this may be severe in the case of modification or deletion requests for legal reasons, e.g. GDPR [i.18]. When implementing the NGSI-LD API on storage systems that do NOT allow modification or deletion, similar problems may be encountered.

4.5.8 Temporal Representation of a Relationship

The temporal evolution of a Relationship (for instance, its historical evolution or future predictions) is composed of the sequence of instances of the referred Relationship during a period of time within its lifetime.

The temporal representation of an NGSI-LD Relationship shall be provided as an Array of JSON-LD objects (or a single JSON-LD object in case only one is present), each one representing an instance of the Relationship (as mandated by clause 4.5.3) at a particular point in time, which is recorded as a Temporal Property of the instance (typically observedAt). See example in annex C, clause C.5.5. In case the Relationship is deleted, an instance of the Relationship is recorded with its object set to the URI “urn:ngsi-ld:null” and the deletedAt Temporal Property set.

Systems should maintain an instanceId for each such Relationship instance. Without such an instanceId, it is not possible to selectively modify or delete temporal information via the NGSI-LD API. The consequences of this may be severe in the case of modification or deletion requests for legal reasons, e.g. GDPR [i.18]. When implementing the NGSI-LD API on storage systems that do NOT allow modification or deletion, similar problems may be encountered.

4.5.9 Simplified temporal representation of an Entity

The NGSI-LD specification defines an alternative, abbreviated temporal representation of Temporal Evolution of Entities, which allows consuming temporal Entity data in a more straightforward manner. The simplified temporal representation of Entities shall be supported by implementations and can be selected by Context Consumers through specific request parameters. An example can be found in annex C, clause C.5.6.

The simplified temporal representation of an Entity shall be a JSON-LD object containing the following members:

Mandatory

“id” whose value shall be a URI that identifies the Entity.
“type” whose value shall be equal to the Entity Type name or an unordered JSON array with multiple Entity Type names in case of an Entity that has multiple Entity Types.

Optional

“@context”, a JSON-LD@context as described in clause 4.4.
For each Property, a member whose key is the Property name (a term), the member value shall be a JSON-LD object labelled with the type “Property”. Such JSON-LD object shall only contain a member whose key shall be “values”. The value of the referred “values” member shall be a JSON-LD Array that shall contain as many array elements as Property instances (i.e. data points of the concerned Property) being represented. Each array element shall be another Array containing exactly two array elements: the first element shall be a Property value and the second element shall correspond to the associated Temporal Property (for instance observedAt).

EXAMPLE 1:

"name": {
  "type": "Property",
  "values": [
    [
      "Joe Bloggs",
      "2022-08-09T18:25:02Z"
    ],
    [
      "Bill Smith",
      "2022-08-10T18:25:02Z"
    ]
  ]
}

For each GeoProperty, a member whose key is the Property name (a term), the member value shall be a JSON-LD object labelled with the type “GeoProperty”. Such JSON-LD object shall only contain a member whose key shall be “values”. The value of the referred “values” member shall be a JSON-LD Array that shall contain as many array elements as GeoProperty instances (i.e. data points of the concerned GeoProperty) being represented. Each array element shall be another Array containing exactly two array elements: the first element shall be a GeoProperty value and the second element shall correspond to the associated Temporal Property (for instance observedAt).
For each LanguageProperty, a member whose key is the Property name (a term), the member value shall be a JSON-LD object labelled with the type “LanguageProperty”. Such JSON-LD object shall only contain a member whose key shall be “languageMaps”. The value of the referred “languageMaps” member shall be a JSON-LD Array that shall contain as many array elements as LanguageProperty instances (i.e. data points of the concerned LanguageProperty) being represented. Each array element shall be another Array containing exactly two array elements: the first element shall be a JSON Object containing a single Attribute with a key called “languageMap” where the value shall correspond to a LanguageProperty languageMap and the second element shall correspond to the associated Temporal Property (for instance observedAt).

EXAMPLE 2:

"says": {
  "type": "LanguageProperty",
  "languageMaps": [
    [
      {"languageMap": {"en": "yes", "fr": "oui"}},
      "2022-08-09T18:25:02Z"
    ],
    [
      {"languageMap": {"en": "no", "fr": "non"}},
      "2022-08-10T18:25:02Z"
    ]
  ]
}

For each ListProperty, a member whose key is the Property name (a term), the member value shall be a JSON-LD object labelled with the type “ListProperty”. Such JSON-LD object shall only contain a member whose key shall be “valueLists”. The value of the referred “valueLists” member shall be a JSON-LD Array that shall contain as many array elements as ListProperty instances (i.e. data points of the concerned ListProperty) being represented. Each array element shall be another array containing exactly two elements: the first element shall be an ordered array of Property values, and the second element shall correspond to the associated Temporal Property (for instance observedAt).

EXAMPLE 3:

"period": {
  "type": "ListProperty",
  "valueLists": [
    [
      ["First", "Second", "Third", "Fourth"],
      "2022-08-09T18:25:02Z"
    ],
    [
      ["1st", "2nd", "3rd", "4th"],
      "2022-08-10T18:25:02Z"
    ]
  ]
}

For each JsonProperty, a member whose key is the Property name (a term), the member value shall be a JSON-LD object labelled with the type “JsonProperty”. Such JSON-LD object shall only contain a member whose key shall be “jsons”. The value of the referred “jsons” member shall be a JSON-LD Array that shall contain as many array elements as JsonProperty instances (i.e. data points of the concerned JsonProperty) being represented. Each array element shall be another Array containing exactly two array elements: the first element shall be a JSON Object containing a single Attribute with a key called “json”, where the value shall correspond to raw JSON data that cannot be held in JSON-LD format and the second element shall correspond to the associated Temporal Property (for instance observedAt).

EXAMPLE 4:

"parkingTickets": {
  "type": "JsonProperty",
  "jsons": [
    [
      {
        "json": [ 
          {
            "id": "85a6cc52-0589-45f9",
            "value": "Overstay 60 minutes"
          }
        ],
      },
      "2022-08-09T18:25:02Z"
    ],
    [
      {
        "json": [
          {
            "id": "85a6cc52-0589-45f9",
            "value": "Overstay 60 minutes"
          },
          {
            "id": "x5c56s-0589-45f9",
            "value": "Overstay 45 minutes"
          }
        ]
      },
      "2022-08-10T18:25:02Z"
    ]
  ]
}

For each VocabProperty, a member whose key is the Property name (a term), the member value shall be a JSON-LD object labelled with the type “VocabProperty”. Such JSON-LD object shall only contain a member whose key shall be “vocabs”. The value of the referred “vocabs” member shall be a JSON-LD Array that shall contain as many array elements as VocabProperty instances (i.e. data points of the concerned VocabProperty) being represented. Each array element shall be another Array containing exactly two array elements: the first element shall be a JSON Object containing a single Attribute with a key called “vocab”, where the value shall correspond to a VocabProperty vocab and the second element shall correspond to the associated Temporal Property (for instance observedAt).

EXAMPLE 5:

"gender": {
  "type": "VocabProperty",
  "vocabs": [
    [
      {"vocab": "Male"},
      "2022-08-09T18:25:02Z"
    ],
    [
      {"vocab": "Female"},
      "2022-08-10T18:25:02Z"
    ]
  ]

}

For each Relationship, a term whose key is the Relationship name (a term). The member value shall be a JSON-LD object labelled with the type “Relationship”. Such JSON-LD object shall only contain a member whose key shall be “objects”. The value of the referred “objects” member shall be a JSON-LD Array that shall contain as many array elements as Relationship instances (i.e. data points of the concerned Relationship) being represented. Each array element shall be another array containing exactly two elements: the first element shall be a Relationship object (a URI or array of URIs) and the second element shall correspond to the associated Temporal Property (for instance observedAt).

EXAMPLE 6:

"spouse": {
  "type": "Relationship",
  "objects": [
    [
      "urn:ngsi-ld:Person:123455",
      "2022-08-09T18:25:02Z"
    ],
    [
      "urn:ngsi-ld:Person:999999",
      "2022-08-10T18:25:02Z"
    ]
  ]
}

EXAMPLE 7:

"activeDevices": {
  "type": "Relationship",
  "objects": [
    [
      ["urn:ngsi-ld:Device:14142", "urn:ngsi-ld:Device:13562"],
      "2022-08-09T18:25:02Z"
    ],
    [
      ["urn:ngsi-ld:Device:14142", "urn:ngsi-ld:Device:13562", "urn:ngsi-ld:Device:37309"],
      "2022-08-10T18:25:02Z"
    ]
  ]
}

For each ListRelationship, a term whose key is the Relationship name (a term), the member value shall be a JSON-LD object labelled with the type “ListRelationship”. Such JSON-LD object shall only contain a member whose key shall be “objectLists”. The value of the referred“objectLists” member shall be a JSON-LD Array that shall contain as many array elements as ListRelationship instances (i.e. data points of the concerned ListRelationship) being represented. Each array element shall be another array containing exactly two elements: the first element shall be an ordered array of Relationship objects (URIs) and the second element shall correspond to the associated Temporal Property (for instance observedAt).

EXAMPLE 7:

"membersPresent": {
  "type": "ListRelationship",
  "objectLists": [
    [
      ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"],
      "2022-08-09T18:25:02Z"
    ],
    [
      ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Eve", "urn:ngsi-ld:Person:Mallory"],
      "2022-08-10T18:25:02Z"
    ]
  ]
}

4.5.10 Entity Type List Representation

The entity type list representation is used to consume information about entity types. The entity type list representation shall be a JSON-LD object containing the following members:

Mandatory

“id” whose value shall be a URI that identifies the entity type list.
“type”: the fixed value “EntityTypeList”.
“typeList”: JSON-LD array containing the entity type names.

Optional

“@context” a JSON-LD @context as described in clause 4.4.

4.5.11 Detailed Entity Type List Representation

The detailed entity type list representation is used to consume detailed information about entity types including the names of attributes that instances of each entity type can have. The detailed entity type list representation shall be an array of JSON-LD objects containing the following members:

Mandatory

“attributeNames”: JSON-LD array containing the names of attributes that instances of the entity type can have.
“id” whose value shall be the URI that identifies the entity type.
“type”: the fixed value “EntityType”.
“typeName”: name of entity type, short name if contained in @context.

Optional

“@context” a JSON-LD @context as described in clause 4.4.

4.5.12 Entity Type Information Representation

The entity type information representation is used to consume detailed information about an entity type. The entity type information representation shall be a JSON-LD object containing the following members:

Mandatory

“id” whose value shall be the URI that identifies the entity type.
“type”: the fixed value “EntityTypeInfo”.
“typeName”: the URI that identifies the entity type (short name in case of availability in @context).

Optional

“@context” a JSON-LD @context as described in clause 4.4.

4.5.13 Attribute List Representation

The attribute list representation is used to consume information about attributes. The attribute list representation shall be a JSON-LD object containing the following members:

Mandatory

“attributeList”: JSON-LD array containing the attribute names.
“id”: whose value shall be a URI that identifies the attribute list.
“type”: the fixed value “AttributeList”.

Optional

“@context”: a JSON-LD @context as described in clause 4.4.

4.5.14 Detailed Attribute List Representation

The detailed attribute list representation is used to consume detailed information about attributes including the names of entity types that have instances with attributes, which have the respective attribute name. The detailed attribute list representation shall be an array of JSON-LD objects containing the following members:

Mandatory

“attributeName”: the URI that identifies the attribute (short name in case of availability in @context).
“id”: whose value shall be the URI that identifies the attribute.
“type”: the fixed value “Attribute”.

Optional

“@context”: a JSON-LD @context as described in clause 4.4.
“typeNames”: an array of the names of entity types that have instances with attributes, which have the respective attribute name.

4.5.15 Attribute Information Representation

The attribute information representation is used to consume detailed information about an attribute. The attribute information representation shall be a JSON-LD object containing the following members:

Mandatory

“attributeName”: the URI that identifies the attribute (short name in case of availability in @context).
“id”:whose value shall be the URI that identifies the attribute.
“type”: the fixed value “Attribute”.

Optional

“@context”: a JSON-LD @context as described in clause 4.4.
“attributeCount”: number of instances of this attribute.
“attributeTypes”: an array of attribute types (e.g. Property, Relationship, GeoProperty) for which instances with the attribute name exist.
“typeNames”: an array of the names of entity types that have instances with attributes, which have the respective attribute name.

4.5.16 GeoJSON Representation of Entities

4.5.16.0 Foreword

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 [8] and/or GeoJSON-LD [i.20].

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

4.5.16.1 Top-level “geometry” field selection algorithm

A parameter of the request (named geometryProperty) may be used to indicate the name of the GeoProperty to be selected. If this parameter is not present, then the default name of “location” shall be used.

If the selected GeoProperty has multiple instances as described in clause 4.5.5, either a datasetId shall be specified, in order to define which instance of the value is to be selected, or a default attribute instance exists, which is then selected, if no datasetId was specified.

If an entity lacks the GeoProperty as specified or the value does not hold a valid GeoJSON geometry object then the geometry shall be undefined and returned with a value of null - which is syntactically valid GeoJSON.

4.5.16.2 GeoJSON Representation of an individual Entity

The GeoJSON representation of a spatially bounded Entity is defined as a single GeoJSON Feature object including the following members:

Mandatory

“geometry”: The value of the selected GeoProperty (a GeoJSON geometry object) used to define the spatial location of the Entity. Note that no sub-Attributes of the selected GeoProperty are present in the representation.
“id”: the Entity id.
“properties”: A JSON object containing the following members:

“type”: the Entity Type name of the Entity or an unordered JSON array with the Entity Type names of the Entity.
One member for each Property (including the selected GeoProperty) as per the rules stated in clause 4.5.2. In case of multiple Property instances with the same Property name as described in clause 4.5.5, all instances are provided as an unordered JSON array.
One member for each Relationship as per the rules stated in clause 4.5.3. In case of multiple Relationship instances with the same Relationship name as described in clause 4.5.5, all instances are provided as an unordered JSON array.

“type”: the fixed value“Feature”.

Optional

A JSON-LD @context as described in clause 4.4 if requested as part of the payload body.

This representation shall be fully compliant with Feature as defined within IETF RFC 7946 [8].

An example can be found in annex C, clause C.2.3.

4.5.16.3 GeoJSON Representation of Multiple Entities

The GeoJSON representation of a list of spatially bounded Entities is defined as a single GeoJSON FeatureCollection object containing an array of GeoJSON Feature objects as follows:

Mandatory

“type”: the fixed value “FeatureCollection”.
“features”: a JSON array of GeoJSON Feature objects as defined in clause 4.5.16.2. Note that separate @context elements for each Feature will not be present in the payload body.

Optional

A JSON-LD @context as described in clause 4.4 if requested as part of the payload body.

This representation shall be fully compliant with FeatureCollection as defined within IETF RFC 7946 [8].

An example can be found in annex C, clause C.2.3.

4.5.17 Simplified GeoJSON Representation of Entities

4.5.17.0 Foreword

When both simplified (see clause 4.5.4) and GeoJSON representation is requested, the following simplified GeoJSON representation compatible with GIS systems shall be returned.

4.5.17.1 Simplified GeoJSON Representation of an individual Entity

The simplified GeoJSON representation of a spatially bounded Entity is defined as a single GeoJSON Feature object as follows:

Mandatory

“geometry”: The value of the selected GeoProperty (a GeoJSON geometry object) used to define the spatial location of the Entity.
“id”: the Entity id.
“type”: the fixed value “Feature”.
“properties”: An array containing the following attributes:

“type”: Mandatory - the Entity Type name of the Entity or an unordered JSON array with the Entity Type names of the Entity.
For each Property (including the selected GeoProperty) a member whose key is the Property name (a term) and whose value is the Property Value. In the multi-attribute case, each Property consists of a key-value pair, the key being the Property name (a term) and the value being a JSON Object, which contains a single Attribute with a key called “dataset”, and its value in turn is a JSON Object holding a series of key-value pairs, one for each datasetId, where the value corresponds to the simplified representation of the property value. The default datasetId (where present) is represented by the JSON-LD keyword “@none”.
For each Relationship a term whose key is the Relationship name (a term) and whose value is the Relationship’s Object (represented as a URI). In the multi-attribute case, each Relationship consists of a key-value pair, the key being the Relationship name (a term) and the value being a JSON Object containing a single Attribute with a key called “dataset” and its value in turn is a JSON Object holding a series of key-value pairs, one for each datasetId where the value corresponds to the object of the relationship. The default datasetId (where present) is represented by the JSON-LD keyword “@none”.

Optional

A JSON-LD @context as described in clause 4.4 if requested as part of the payload body.

The selection of the geometry field is defined in clause 4.5.16.1.

This representation shall be fully compliant with Feature as defined within IETF RFC 7946 [8].

An example can be found in annex C, clause C.2.3.

4.5.17.2 Simplified GeoJSON Representation of multiple Entities

The simplified GeoJSON representation of a list of spatially bounded Entities is defined as a single GeoJSON FeatureCollection object containing an array of GeoJSON Feature objects as follows:

Mandatory

“features”: a JSON array of simplified GeoJSON Feature objects as defined in clause 4.5.17.1. Note that separate @context elements for each Feature will not be present in the payload body.
“type”: the fixed value “FeatureCollection”.

Optional

A JSON-LD @context as described in clause 4.4 if requested as part of the payload body.

This representation shall be fully compliant with FeatureCollection as defined within IETF RFC 7946 [8].

4.5.18 NGSI-LD LanguageProperty Representations

4.5.18.1 Introduction

NGSI-LD defines a specialized type of Property named LanguageProperty, defined by the NGSI-LD @context described by the present document in clause 4.4.

When dealing with NGSI-LD Entities, implementations shall interpret the JSON-LD nodes of type LanguageProperty as per clause 4.5.18.2 (when in normalized representation) or clause 4.5.18.3 (when in concise representation).

Both normalized and concise representation of LanguageProperties shall be supported by implementations and can be selected by Context Consumers through specific request parameters. An example of this representation can be found in annex C, clause C.2.2.

4.5.18.2 Normalized NGSI-LD LanguageProperty

An NGSI-LD LanguageProperty shall be represented in normalized representation by a member whose key is the Property name (a term), whose value is the same as the JSON-LD object in NGSI-LD Property Representation defined in clause 4.5.2.2, with the following differences:

Mandatory

“languageMap”: a JSON object consisting of a set of a non-empty language tags as defined by IETF RFC 5646 [28] or the language tag “@none” which represents a default language, with each language tag mapping to a single string or array of strings. It represents a more specialized value.

An NGSI-LD Null used during partial update patch and merge patch (see clauses 5.5.8 and 5.5.12) shall be encoded as the JSON object {“@none”: “urn:ngsi-ld:null”}. The same representation is also used to indicate a deletion in notifications and in temporal evolutions for encoding a deleted LanguageProperty.
“type”: the fixed value “LanguageProperty”.

Output Only

“previousLanguageMap”: only provided only in the case of notifications and only if the showChanges option is explicitly requested. It represents the previous LanguageProperty languageMap, before the triggering change. The representation is the same as that of “languageMap”.

Furthermore, an NGSI-LD LanguageProperty in the normalized representation shall never include the following members:

Prohibited

“unitCode”: shall never be present, as language maps are always strings and hence unitless.
“value”and “previousValue”: shall never be present, as value is a generalization of languageMap.

4.5.18.3 Concise NGSI-LD LanguageProperty

An NGSI-LD LanguageProperty shall be represented in concise but lossless representation by a member whose key is the Property name (a term), whose value is the same as the JSON-LD object in NGSI-LD Property Representation defined in clause 4.5.2.3, with the following differences:

Mandatory

“languageMap”: a JSON object consisting of a set of a non-empty language tags as defined by IETF RFC 5646 [28] or the language tag “@none”which represents a default language, with each language tag mapping to a single string or array of strings. It represents a more specialized value.

An NGSI-LD Null used during partial update patch and merge patch (see clauses 5.5.8 and 5.5.12) shall be encoded as the JSON object {“@none”: “urn:ngsi-ld:null”}. The same representation is also used to indicate a deletion in notifications and the temporal evolutions for encoding a deleted LanguageProperty.

Optional

“type”: If missing, “LanguageProperty” can be inferred by the presence of the “languageMap” attribute.

Output Only

“previousLanguageMap”: only provided only in the case of notifications and only if the showChanges option is explicitly requested. It represents the previous LanguageProperty languageMap, before the triggering change. The representation is the same as that of “languageMap”.

Furthermore, an NGSI-LD LanguageProperty in the concise representation shall never include the following members:

Prohibited

“unitCode”: shall never be present, as language maps are always strings and hence unitless.
“value” and “previousValue”: shall never be present, as it is a generalization of “languageMap”.

Notwithstanding the definition above, during partial update patch and merge patch (see clauses 5.5.8 and 5.5.12), an NGSI-LD LanguageProperty with a value of NGSI-LD Null without a datasetId should be represented in a concise representation by a member whose key is the LanguageProperty name (a term) and whose value is “urn:ngsi-ld:null”.

4.5.19 Aggregated temporal representation of an Entity

4.5.19.0 Foreword

The NGSI-LD specification defines an alternative temporal representation of Entities, called aggregated temporal representation, which allows consuming temporal Entity data after applying an aggregation function on the values of the Attribute instances. The aggregated temporal representation of Entities shall be supported by implementations supporting the temporal representation of Entities and can be selected by Context Consumers through specific request parameters. An example can be found in annex C, clause C.5.14.

The aggregation function is applied according to the following principles:

An aggregation method specifies the function used to aggregate the values (e.g. sum, mean, etc.). A Context Consumer can ask for many aggregation methods in one request.
The duration of an aggregation period specifies the duration of each period to be used when applying the aggregation function on the values of a Temporal Entity.

The aggregated temporal representation of an Entity shall include the following:

A JSON-LD object containing the following members:

id, type and @context as described in clause 4.5.1.
For each Property a member whose key is the Property name (a term). The member value shall be a JSON-LD object labelled with the type “Property”. Such JSON-LD object shall contain one member per aggregation method requested by the Context Consumer. Each member uses the aggregation method name as a key. The value of each member shall be a JSON-LD Array that shall contain as many array elements as there are periods in the time range of the query. Each array element shall be another Array containing exactly three array elements in the following order:

the value obtained after applying the aggregation method over the period;

the start DateTime of the corresponding period;

the end DateTime of the corresponding period.

For each Relationship a term whose key is the Relationship name (a term). The member value shall be a JSON-LD object labelled with the type “Relationship”. Such JSON-LD object shall contain one member per aggregation method requested by the Context Consumer. Each member uses the aggregation method name as a key. The value of each member shall be a JSON-LD Array that shall contain as many array elements as there are periods in the time range of the query. Each array element shall be another array containing exactly three array elements in the following order:

the value obtained after applying the aggregation method over the period;

the start DateTime of the corresponding period;

the end DateTime of the corresponding period.

An example of this aggregated temporal representation can be found in annex C, clause C.5.14.

4.5.19.1 Supported behaviours for aggregation functions

In order to support such aggregation functions, two parameters are defined:

aggrMethods, to express the aggregation methods to apply.
aggrPeriodDuration to express the duration of the period to consider in each step of the aggregation.

The duration is expressed using the ISO 8601 [17] Duration Representation and in particular using the following format and conventions:

The duration shall be a string in the format P[n]Y[n]M[n]DT[n]H[n]M[n]S or P[n]W, where [n] is replaced by the value for each of the date and time elements that follow the [n], P is the duration designator and T is the time designator. For example, “P3Y6M4DT12H30M5S” represents a duration of “three years, six months, four days, twelve hours, thirty minutes, and five seconds”.
Date and time elements including their designator may be omitted if their value is zero.
Lower-order elements may be omitted for reduced precision.
A duration of 0 second (e.g. expressed as “PT0S” or “P0D”) is valid and is interpreted as a duration spanning the whole time range specified by the temporal query.
Alternative representations based on combined date and time representations are not allowed.

The values supported by the aggrMethods parameter are the following:

aggrMethods = “avg” / “distinctCount” / “max” / “min” / “stddev” / “sum” / “sumsq” / “totalCount”

The semantics of the different aggregation methods defined above is as follows, and shall be supported by compliant implementations:

Table 4.5.19.1-1: Semantics of aggregation methods for Properties on JSON native data types

Aggregation Method	JSON String	JSON Number	JSON Object	JSON Array	JSON Boolean (see note)
avg	N/A	Calculate the average of the values inside the period	N/A	Calculate the average number of the sizes of the arrays inside the period	Calculate the average of the values inside the period
distinctCount	Calculate the count of distinct values inside the period
max	Calculate the last value in lexicographical order inside the period	Calculate the maximum value inside the period	N/A	Calculate the maximum size of the arrays inside the period	Calculate the maximum value inside the period
min	Calculate the first value in lexicographical order inside the period	Calculate the minimum value inside the period	N/A	Calculate the minimum size of the arrays inside the period	Calculate the minimum value inside the period
stddev	N/A	Calculate the standard deviation of the values inside the period	N/A	N/A	Calculate the standard deviation of the values inside the period
sum	N/A	Calculate the sum of the values inside the period	N/A	Calculate the sum of the sizes of the arrays inside the period	Calculate the sum of the values inside the period
sumsq	N/A	Calculate the sum of the square of the values inside the period	N/A	N/A	Calculate the sum of the square of the values inside the period
totalCount	Calculate the number of times the value has been updated inside the period
NOTE: For the purpose of aggregation, true is considered as a value of 1, false is considered as a value of 0.

Table 4.5.19.1-2: Semantics of aggregation methods for Properties on other supported data types

Aggregation Method	DateTime	Date	Time	URI
avg	N/A	N/A	Calculate the average time inside the period (e.g. to apply on an event that occurs at non fixed times, like the time a car enters a given parking)	N/A
distinctCount	Calculate the count of distinct values inside the period
max	Calculate the maximum value inside the period	Calculate the maximum value inside the period	Calculate the maximum value inside the period	N/A
min	Calculate the minimum value inside the period	Calculate the minimum value inside the period	Calculate the minimum value inside the period	N/A
stddev	N/A	N/A	N/A	N/A
sum	N/A	N/A	N/A	N/A
sumsq	N/A	N/A	N/A	N/A
totalCount	Calculate the number of times the value has been updated inside the period

Table 4.5.19.1-3: Semantics of aggregation methods for Relationships

Aggregation Method	Relationship
avg	N/A
distinctCount	Calculate the count of distinct relationships targets inside the period
max	N/A
min	N/A
stddev	N/A
sum	N/A
sumsq	N/A
totalCount	Calculate the number of times the relationship has been updated inside the period

4.5.20 NGSI-LD VocabProperty Representations

4.5.20.1 Introduction

NGSI-LD defines a specialized type of Property named VocabProperty, defined by the NGSI-LD @context described by the present document in clause 4.4.

When dealing with NGSI-LD Entities, implementations shall interpret the JSON-LD nodes of type VocabProperty as per clause 4.5.20.2 (when in normalized representation) or clause 4.5.20.3 (when in concise representation).

Both normalized and concise representation of VocabProperties shall be supported by implementations and can be selected by Context Consumers through specific request parameters. An example of this representation can be found in annex C, clause C.2.2.

4.5.20.2 Normalized NGSI-LD VocabProperty

An NGSI-LD VocabProperty shall be represented in normalized representation by a member whose key is the Property name (a term), whose value is the same as the JSON-LD object in NGSI-LD Property Representation defined in clause 4.5.2.2, with the following differences:

Mandatory

“type”: the fixed value ”VocabProperty”.
“vocab”: a JSON object consisting of a single string or array of strings which can be type coerced into an IRI or array of IRIs. It represents a more specialized value.

Output Only

“previousVocab”: only provided in case of notifications and only if the showChanges option is explicitly requested. It represents the previous VocabProperty vocab, before the triggering change. The representation is the same as that of “vocab”.

Furthermore, an NGSI-LD VocabProperty in the normalized representation shall never include the following members:

Prohibited

“unitCode”: shall never be present, as vocabs are always strings and hence unitless.
“value” and “previousValue”: shall never be present, as value is a generalization of vocab.

4.5.20.3 Concise NGSI-LD VocabProperty

An NGSI-LD VocabProperty shall be represented in concise but lossless representation by a member whose key is the Property name (a term), whose value is the same as the JSON-LD object in NGSI-LD Property Representation defined in clause 4.5.2.3, with the following differences.

Mandatory

“vocab”: a JSON object consisting of a single string or array of strings which can be type coerced into an IRI or array of IRIs. It represents a more specialized value.

Optional

“type”: If missing, ”VocabProperty” can be inferred by the presence of the “vocab” attribute.

Output Only

“previousVocab”: only provided only in the case of notifications and only if the showChanges option is explicitly requested. It represents the previous VocabProperty vocab, before the triggering change. The representation is the same as that of “vocab”.

Furthermore, an NGSI-LD VocabProperty in the concise representation shall never include the following members:

Prohibited

“unitCode”: shall never be present, as vocabs are always strings and hence unitless.
“value” and “previousValue”: shall never be present, as it is a generalization of vocab.

4.5.21 NGSI-LD ListProperty Representations

4.5.21.1 Introduction

NGSI-LD defines a specialized type of Property named ListProperty, defined by the NGSI-LD @context described by the present document in clause 4.4.

When dealing with NGSI-LD Entities, implementations shall interpret the JSON-LD nodes of type ListProperty as per clause 4.5.21.2 (when in normalized representation) or clause 4.5.21.3 (when in concise representation).

Both normalized and concise representation of ListProperties shall be supported by implementations and can be selected by Context Consumers through specific request parameters. An example of this representation can be found in annex C, clause C.2.2.

4.5.21.2 Normalized NGSI-LD ListProperty

An NGSI-LD ListProperty shall be represented in normalized representation by a member whose key is the Property name (a term), whose value is the same as the JSON-LD object in NGSI-LD Property Representation defined in clause 4.5.2.2, with the following differences:

Mandatory

“type”: the fixed value ”ListProperty”.
“valueList”: a JSON representation ordered array of Property Values (see definition of NGSI-LD Value in clause 3.1). It represents a more specialized value.

An array consisting of a single NGSI-LD Null (explained in clause 4.5.0 and defined in clause 3.1) can be used as the right-hand side of the “valueList” during partial update patch and merge patch (see clauses 5.5.8 and 5.5.12) to indicate a deletion of the ListProperty, as well as in notifications and in temporal evolutions (for encoding a deleted ListProperty).

Output Only

“previousValueList”: only provided only in the case of notifications and only if the showChanges option is explicitly requested. It represents the previous ListProperty valueList, before the triggering change. The representation is the same as that of “valueList”.

Furthermore, an NGSI-LD ListProperty in the normalized representation shall never include the following members:

Prohibited

“value” and “previousValue”: shall never be present, as value is a generalization of valueList.

4.5.21.3 Concise NGSI-LD ListProperty

An NGSI-LD ListProperty shall be represented in concise but lossless representation by a member whose key is the ListProperty name (a term), whose value is the same as the JSON-LD object in NGSI-LD Property Representation defined in clause 4.5.2.3, with the following differences:

Mandatory

“valueList”: a JSON representation of a ordered array of Property Values (see definition of NGSI-LD Value in clause 3.1). It represents a more specialized value.

Optional

“type”: If missing, ”ListProperty” can be inferred by the presence of the “valueList” attribute.

Output Only

“previousValueList”: only provided only in the case of notifications and only if the showChanges option is explicitly requested. It represents the previous ListProperty “valueList”, before the triggering change. The representation is the same as that of “valueList”.

Furthermore, an NGSI-LD ListProperty in the concise representation shall never include the following members:

Prohibited

“value” and “previousValue“: shall never be present, as value is a generalization of valueList.

4.5.22 NGSI-LD ListRelationship Representations

4.5.22.1 Introduction

NGSI-LD defines a specialized type of Relationship named ListRelationship, defined by the NGSI-LD @context described by the present document in clause 4.4.

When dealing with NGSI-LD Entities, implementations shall interpret the JSON-LD nodes of type ListRelationship as per clause 4.5.22.2 (when in normalized representation) or clause 4.5.22.3 (when in concise representation).

Both normalized and concise representation of ListRelationships shall be supported by implementations and can be selected by Context Consumers through specific request parameters. An example of this representation can be found in annex C, clause C.2.2.

4.5.22.2 Normalized NGSI-LD ListRelationship

An NGSI-LD ListRelationship shall be represented in normalized representation by a member whose key is the Relationship name (a term), whose value is the same as the JSON-LD object in NGSI-LD Relationship Representation defined in clause 4.5.3.2, with the following differences:

Mandatory

“objectList”: a JSON representation of an ordered array of Relationship Objects each consisting of a JSON object containing a single Attribute with a key called “object” and its value holding the Relationship’s object represented by a URI.

An array consisting of a single NGSI-LD Null (explained in 4.5.0 and defined in clause 3.1) can be used as the right-hand side of the “objectList” during partial update patch and merge patch (see clauses 5.5.8 and 5.5.12) to indicate a deletion of the ListRelationship, as well as in notifications and in temporal evolutions (for encoding a deleted ListRelationship).

“type”: the fixed value ”ListRelationship”.

Output Only

“entityList”: only provided in case of Linked Entity retrieval, and only if the inline join option is explicitly requested (see clause 4.5.23.2), where it is used to define the target Linked Entities of a ListRelationship’s objectList in normalized representation.
“previousObjectList”: only provided in the case of notifications and only if the showChanges option is explicitly requested. It represents the previous ListRelationship objectList, before the triggering change. The representation is the same as that of “objectList”.

Furthermore, an NGSI-LD ListRelationship in the normalized representation shall never include the following members:

Prohibited

“entity”: shall never be present as entity is a generalization of entityList.
“object” and “previousObject”: shall never be present as object is a generalization of objectList.

4.5.22.3 Concise NGSI-LD ListRelationship

An NGSI-LD ListRelationship shall be represented in concise but lossless representation by a member whose key is the Relationship name (a term), whose value is the same as the JSON-LD object in NGSI-LD Relationship Representation defined in clause 4.5.3.3, with the following differences:

Mandatory

“objectList”: this represents a more specialized object and is represented by an ordered array of either:

a JSON objects containing a single Attribute with a key called “object” and its value holding the Relationship’s object represented by a URI.
Strings representing URIs only, where expansion to Relationship objects can be inferred by the presence of the “objectList” attribute.

Optional

“type”: If missing, “ListRelationship” can be inferred by the presence of the “objectList” attribute.

Output Only

“entityList”: only provided if the inline join option is explicitly requested (see clause 4.5.23.2), where it is used to define the target Linked Entities of a ListRelationship’s “objectList” in concise representation.
“previousObjectList”: only provided only in the case of notifications and only if the showChanges option is explicitly requested. It represents the previous ListRelationship objectList, before the triggering change. Optional. The representation is the same as that of “objectList”.

Furthermore, an NGSI-LD ListRelationship in the concise representation shall never include the following members:

Prohibited

“entity”: shall never be present as entity is a generalization of entityList.
“object” and “previousObject”: shall never be present as object is a generalization of objectList.

4.5.23 NGSI-LD Linked Entity Retrieval

4.5.23.1 Introduction

Since Entities are uniquely identifiable by a URI, it is possible to traverse across the Entity graph directly from a Linking Entity to a Linked Entity. It is therefore sometimes convenient to be able to query or retrieve data via a single Context Broker request and to receive a response including both Linking Entities and dependent Linked Entities directly.

The concept of Entity graph retrieval is a common concept amongst graph databases and it allows for more structured queries (see clause 4.9) and the complete serialization of an Entity and its dependents.

When retrieving Linked Entities, it is necessary to limit retrieval to avoid cascades of an excessive length, duplicates or loops. Only Relationships targeting a locally stored Entity or Relationships annotated with an objectType whose object is an Internal Linked Entity are considered to be retrievable in this manner.

4.5.23.2 Inline Linked Entity Representation

With the inline representation, the Context Broker response shall only consist of Linking Entities - either a single Linking Entity, or an array consisting of Linking Entities. The additional Entity data from Linked Entities is returned via a Sub-Attribute added to annotated Relationships. This inline representation is generated for output only.

An example of this representation can be found in annex C, clause C.2.2.

4.5.23.3 Flattened Linked Entity Representation

With the flattened representation, the Context Broker response shall always consist of an array of Entities. This array will consist of both Linking Entities and Linked Entities (where the retrieved Linked Entities defined by an annotated Relationship), are appended to the array. This flattened representation allows for batch operations (see clauses 5.6.7, 5.6.8, 5.6.9 and 5.6.10) be applied directly using the response from the Context Broker.

An example of this representation can be found in annex C, clause C.2.2.

4.5.24 NGSI-LD JsonProperty Representations

4.5.24.1 Introduction

NGSI-LD defines a specialized type of Property named JsonProperty, defined by the NGSI-LD @context described by the present document in clause 4.4.

When dealing with NGSI-LD Entities, implementations shall interpret the JSON-LD nodes of type JsonProperty as per clause 4.5.24.2 (when in normalized representation) or clause 4.5.24.3 (when in concise representation).

Both normalized and concise representation of JsonProperties shall be supported by implementations and can be selected by Context Consumers through specific request parameters. An example of this representation can be found in annex C, clause C.2.2.

4.5.24.2 Normalized NGSI-LD JsonProperty

An NGSI-LD JsonProperty shall be represented in normalized representation by a member whose key is the Property name (a term), whose value is the same as the JSON-LD object in NGSI-LD Property Representation defined in clause 4.5.2.2, with the following differences:

Mandatory

“type”: the fixed value ”JsonProperty”.
“json”: a raw JSON object (or array of objects) which contains data which is not available for JSON-LD interpretation. This means that the attributes within the JSON object are never subject to JSON-LD term expansion or compaction. It represents a more specialized value.

Output Only

“previousJson”: only provided in case of notifications and only if the showChanges option is explicitly requested. It represents the previous JsonProperty json, before the triggering change. The representation is the same as that of “json”.

Furthermore, an NGSI-LD JsonProperty in the normalized representation shall never include the following members:

Prohibited

“unitCode”: shall never be present, as raw JSON objects are unitless.
“value” and “previousValue”: shall never be present, as value is a generalization of json.

4.5.24.3 Concise NGSI-LD JsonProperty

An NGSI-LD JsonProperty shall be represented in concise but lossless representation by a member whose key is the Property name (a term), whose value is the same as the JSON-LD object in NGSI-LD Property Representation defined in clause 4.5.2.3, with the following differences:

Mandatory

“json”: a raw JSON object which contains data which is not available for JSON-LD interpretation. This means that the attributes within the JSON object are never subject to JSON-LD term expansion or compaction. It represents a more specialized value.

Optional

“type”: If missing, ”JsonProperty” can be inferred by the presence of the “json” attribute.

Output Only

“previousJson”: only provided in case of notifications and only if the showChanges option is explicitly requested. It represents the previous JsonProperty json, before the triggering change. The representation is the same as that of “json”.

Furthermore, an NGSI-LD JsonProperty in the concise representation shall never include the following members:

Prohibited

“unitCode”: shall never be present, as raw JSON objects are unitless.
“value” and “previousValue”: shall never be present, as it is a generalization of json.

4.5.25 NGSI-LD EntityMap Representation

The EntityMap representation is used by Context Brokers to ensure unity when querying across distributed operations. It is an active mapping of Context Source Registrations to Entities which are relevant to an ongoing Context Information Consumption request (see clause 4.3.6.7). The EntityMap representation shall be a JSON-LD object containing the following members:

Mandatory

“id”: whose value shall be the URI that identifies the attribute.
“type”: the fixed value “EntityMap”.
“expiredBy”: a DateTime string (as defined in clause 4.6.3) for encoding a timestamp indicating the time at which the EntityMap can no longer be used.

Optional

“@context”: a JSON-LD @context as described in clause 4.4.

Output Only

“entityMap”: a JSON-LD index map holding a unique list of entity ids (URIs) each of which lists the registrations that were fired by the previous request and successfully returned data.
“linkedMaps”: a JSON-LD index map holding a unique list of Context Source Registrations ids (URIs) each of which lists the entityMap used by a Context Source.

4.6 Data Representation Restrictions

4.6.1 Supported text encodings

NGSI-LD implementations shall support the UTF-8 text encoding format. To avoid interoperability problems, applications shall provide JSON content encoded using UTF-8 and NGSI-LD systems shall also expose such JSON content using UTF-8.

4.6.2 Supported names

Even though the JSON serialization format allows inclusion of any character in the Unicode space, NGSI-LD restricts Entity Type names, Property names and Relationship names to the following ABNF grammar:

nameChar = unicodeNumber / unicodeLetter
nameChar =/ %x5F                  ; _
name = unicodeLetter *nameChar

unicodeNumber is any Unicode character that has Number as a Category [22]. With Unicode-capable regular expression (RegEx) parsers, such a character may be matched by \p{N}.
unicodeLetter is any Unicode character that has Letter as a Category [22]. With Unicode-capable regular expression (RegEx) parsers, such a character may be matched by \p{L}.

In order to avoid name clashing, names can be prefixed as specified by the following BNF grammar:

prefix = unicodeLetter *nameChar
name =/ prefix %x3A unicodeLetter *nameChar ; prefix:name

When receiving a JSON-LD object with a name (Type, Property, Relationship) including characters different than those expressed above, implementations should raise an error of type BadRequestData.

4.6.3 Supported data types for Values

Compliant NGSI-LD implementations shall support the following data types for representing Values:

All the JSON native data types as mandated by IETF RFC 8259 [6], section 3.
All the GeoJSON Geometries [8] with the exception of GeometryCollection.
DateTime string for encoding a timestamp, i.e. a calendar date together with a time of day, expressed in UTC, using the ISO 8601 [17] Complete Representation and in particular using the ‘Extended Format’, as described below:

The timestamp shall be a string containing Year, Month, Day, Hours, Minutes, Seconds and time zone components using the format YYYY-MM-DDThh:mm:ssZ as defined in ISO 8601 [17]. In this representation, the character “-” is used to separate the calendar date components, the character “T” is used to indicate the start of the time-of-day portion, the character “:” is used to separate the time-of-day components, and the trailing character “Z” is used to convey the time zone.
All the referred components shall appear in the string; reduced representations are not permitted.
The Seconds component may optionally contain a decimal fraction. In this case the string shall contain two integer digits, followed by a decimal point and then one or more fractional digits, up to a maximum of six. For example, YYYY-MM-DDThh:mm:ss.ssssssZ. In requests, also a comma instead of a decimal point may be used as separator for compatibility reasons.

NOTE 1:

In previous versions of NGSI-LD, only the comma was supported as ISO 8601 [17] states that it is the preferred option. However, in practice the decimal point is more commonly used .

The trailing timestamp component shall contain the time zone related information and shall always be equal to the character “Z”. Therefore, all timestamps shall be expressed in UTC.

Date string for encoding a calendar date. It uses ISO 8601 [17] Complete Representation using the ‘Extended Format’, as described below:

It shall be a string containing Year, Month, Day components using the format YYYY-MM-DD as defined in ISO 8601 [17]. In this representation, the character “-” is used to separate the calendar date components.
All the referred components shall appear in the string; reduced representations are not permitted.

Time string for encoding a local time expressed in UTC. It uses ISO 8601 [17] Complete Representation using the ‘Extended Format’, as described below:

It shall be a string containing Hours, Minutes and Seconds components using the format hh:mm:ssZ as defined in ISO 8601 [17]. In this representation, the character “:” is used to separate the local time components.
All the referred components shall appear in the string; reduced representations are not permitted.
The Seconds component may optionally contain a decimal fraction. In this case the string shall contain two integer digits, followed by a decimal point and then one or more fractional digits, up to a maximum of six. For example, hh:mm:ss.ssssssZ. In requests, also a comma instead of a decimal point may be used as separator for compatibility reasons.

NOTE 2:

In previous versions of NGSI-LD, only the comma was supported as ISO 8601 [17] states that it is the preferred option. However, in practice the decimal point is more commonly used.

The string shall not contain expressions of the difference between local time and UTC. All representations shall be interpreted as being expressed in UTC.

URI as mandated by ISO 8601 [17], Appendix A, production rule named ‘URI’.

Implementations may support additional data types different to those enumerated above, for instance:

JSON-LD typed value (i.e. a string as the lexical form of the value together with a type, defined by an XSD base type or more generally an IRI).
JSON-LD structured value (e.g. a set, a list).

4.6.4 Supported Content

In principle, context information providers can publish any kind of data serialized in JSON and encoded in UTF-8. Nonetheless, to avoid security problems caused by script injection attacks or other attack vectors, implementations should consider that the incoming data from a client may contain the following characters:

%x3C; <
%x3E; >
%x22; ”
%x27; ’
%x3D; =
%x3B; ;
%x28; (
%x29; )

When receiving entities (context information) encoded in JSON format and containing values that include the above characters, implementations should decide how to resolve the possible security problems that may be generated by the data. In all cases, implementations shall preserve the representation of the content of the values provided by the context information providers and return the original content when replying to context consumption requests.

If implementations decide to raise an error, the error shall be BadRequestData.

4.6.5 Supported data types for LanguageMaps

Compliant NGSI-LD implementations shall support the following data types for representing LanguageMaps:

A JSON object consisting of a series of key-value pairs where the keys shall be JSON strings representing IETF RFC 5646 [28] language codes or the JSON-LD “@none” for representing default when no more specific language is found. and the values shall be JSON strings or arrays of JSON strings. Additionally, the languageMap encoding {“@none”: “urn:ngsi-ld:null”} shall be used to represent an NGSI-LD Null during partial update patch and merge patch (see clauses 5.5.8 and 5.5.12) and for representing deleted Language Properties in notifications and in temporal evolutions.

4.6.6 Ordering of Entities in arrays having more than one instance of the same Entity

Some services (batch operations, clauses 5.6.7, 5.6.8, 5.6.9 and 5.6.10) operate on an array of entities, as input, and if this array contains more than one instance of the same entity, then these entity instances shall come in chronological order, i.e. the first entity instance in the array shall be older than the second, the second shall be older than the third, etc.

Without this assumption, there is no way for the request to be treated correctly, as the entity instances are often used for replacing or modifying the prior entity instance.

4.7 Geospatial Properties

4.7.1 GeoJSON Geometries

Geospatial Properties in NGSI-LD shall be represented using GeoJSON Geometries [8]. With the aim of highlighting and encoding those Properties which convey geospatial characteristics, NGSI-LD defines a special type of Property named GeoProperty, defined by the Core NGSI-LD @context described by the present document in clause 4.4.

When dealing with NGSI-LD Entities, implementations shall interpret JSON-LD nodes of type GeoProperty just as conventional Properties but with the additional requirement that the Value corresponding to such Property shall be a GeoJSON Geometry. All the Geometries defined by [8] are allowed except GeometryCollection. In addition, implementations should take the necessary steps to create the corresponding geo-indexes so that information can be properly returned when geo-queries are executed.

NGSI-LD defines the following Properties of type GeoProperty. Preferably these Properties should be used if they semantically fit, but if necessary, additional Properties of type GeoProperty can be defined by Context Producers:

location is defined as the geospatial Property representing the geographic location of the Entity, e.g. the location of a building or the current location of a car.
observationSpace is defined as the geospatial Property representing the geographic location that is being observed, e.g. by a sensor. For example, in the case of a camera, the location of the camera and the observation space are different and can be disjoint.
operationSpace is defined as the geospatial Property representing the geographic location in which an Entity, e.g. an actuator is active. For example, a crane can have a certain operation space.

The defined Properties can also be used as part of Context Source Registrations (see clause 5.2.9). In this case they represent locations in which Entities with the respective geospatial Properties are contained. For example, a Context Source that monitors the location of cars in a city may be represented by a Context Source Registration whose Property location corresponds to the space of the city in which the location of cars is monitored.

4.7.2 Representation of GeoJSON Geometries in JSON-LD

There are certain types of GeoJSON geometries, for instance GeoJSON Polygon, whose coordinates are represented using nested array structures (through the coordinates member). Such representation may introduce serialization problems when transforming JSON-LD content into RDF graphs.

Also, when using whole GeoJSON geometries (consisting of type and coordinates) in an NGSI-LD document, its JSON syntax is only preserved in the regular JSON-LD representation (with separate @context), but not in an expanded representation. To handle resulting problems, optionally, whole GeoJSON geometries can be represented as a JSON string.

Implementations shall accept the referred encoded string value, if and only if, it can be parsed into a JSON Object, as mandated by IETF RFC 8259 [6], meeting the syntax and restrictions mandated by IETF RFC 7946 [8] when representing a valid Geometry of the type specified.

For the avoidance of doubt, regular encodings of GeoJSON geometries (as JSON Object) shall also be accepted by implementations, but Context Producers should consider the implications in terms of RDF compatibility.

GeoJSON coordinates shall be considered as consisting of values of a JSON-LD floating point number data type. The degree of precision of a latitude and longitude (and optional altitude) held within a context broker will depend upon the implementation. Implementors should note that the GeoJSON specification itself recommends 6 decimal places for latitude and longitude which equates to roughly 10cm of precision.

4.7.3 Concise NGSI-LD GeoProperty

Notwithstanding the restrictions defined in clause 4.5.2.3, an NGSI-LD GeoProperty without additional sub-attributes shall be represented in a concise but lossless representation by a member whose key is the Property name (a term) and whose value is the Property Value (see definition of terms in clause 3.1) which itself is also a supported GeoJSON geometry.

Mandatory

“type”: shall be a supported GeoJSON geometry type as defined in clause 4.7.1.
“coordinates”: shall be present, as defined by the relevant GeoJSON Geometry [8].

When parsing a geospatial value submitted in the concise representation, it shall be possible for the NGSI-LD system to infer the GeoProperty type. Error handing of the payload is left ambiguous if the NGSI-LD system is unable to distinguish a payload as either a Property or a GeoProperty.

Furthermore, an NGSI-LD GeoProperty which includes additional Properties or Relationships shall be treated in the same manner as an ordinary NGSI-LD Property (see clause 4.5.2.3) with the exception that if the Property value resolves to a supported GeoJSON geometry, the type “GeoProperty” shall be inferred.

4.8 Temporal Properties

NGSI-LD defines the following Properties of type TemporalProperty that shall be supported by implementations:

observedAt is defined as the temporal Property at which a certain Property or Relationship became valid or was observed. For example, a temperature Value was measured by the sensor at this point in time.
createdAt is defined as the temporal Property at which the Entity, Property or Relationship was entered into an NGSI-LD system.
modifiedAt is defined as the temporal Property at which the Entity, Property or Relationship was last modified in an NGSI-LD system, e.g. in order to correct a previously entered incorrect value.
deletedAt is defined as the temporal Property at which the Entity, Property or Relationship was deleted from an NGSI-LD system.
expiresAt is defined as the temporal Property at which the Entity, Property, Relationship, CSourceRegistration, Subscription or Snapshot should be deleted from an NGSI-LD system.
lastUsedAt is defined as the temporal Property at which a Snapshot has been most recently used, i.e. when the most recent operation has been executed on this Snapshot.

Temporal Properties in NGSI-LD shall be represented based on the DateTime data type as mandated by clause 4.6.3.

NOTE 1:

For simplicity reasons, a TemporalProperty is represented only by its Value, i.e. no Properties of TemporalProperty nor Relationships of TemporalProperty can be conveyed. In more formal language, a TemporalProperty does not allow reification.

NOTE 2:

It is important to remark that the term TemporalProperty has been reserved for the semantic tagging of non-reified structural timestamps ( observedAt , createdAt , modifiedAt, deletedAt , expiresAt ), which capture the temporal evolution of Attributes. Only such structural timestamps can be used as timeproperty in Temporal Queries as mandated by clause 4.11 .

NOTE 3:

User-defined Properties whose value is a time value ( Date, DateTime or Time ) are defined as Property , not as TemporalProperty , and are serialized in NGSI-LD as shown in annex C, clause C.6 .

Whenever a TemporalProperty value is unknown by a registered Context Source, the Property shall be omitted rather than sending an error response.

4.9 NGSI-LD Query Language

The NGSI-LD Query Language shall be supported by implementations. It is intended to:

filter out Entities by Attribute Values (target is the value member of a Property, see Table 5.2.5‑1, or the object member of a Relationship, see Table 5.2.6‑1);
filter out Context Sources by the values of properties that describe them, defined when Context Sources are registered (target is the name of a Context Source Property member of the CSourceRegistration, see Table 5.2.9-1).
filter out Snapshots by the values of the Snapshot data type members, i.e. when filtering Snapshots, only the names of the members defined for Snapshot in Table 5.2.43‑1 are allowed values for AttrName.

In this clause, three string parameters are defined in order to fully specify an NGSI-LD Query:

q, to express the desired query;
expandValues, to define the list of attributes whose values should be expanded against the supplied @context using JSON-LD type coercion prior to executing the query in the Context Broker.

Optional

jsonKeys, to define the list of attributes whose values uninterpretable as JSON-LD and should not be expanded against the supplied @context using JSON-LD type coercion prior to executing the query in the Context Broker. Optional

In case of HTTP binding, whenever the string acting as a filter is part of the HTTP binding’s URI, then it shall be URI-encoded (percent-encoded, as described in IETF RFC 3986 [5]).

The grammar that encodes the syntax of the q parameter, expressed in ABNF format [12], is the NGSI-LD Query Language. It is described below (it has been validated using <https://github.com/ietf-tools/bap>), and it shall be supported by implementations:

Query = (QueryTerm / QueryTermAssoc) *(LogicalOp (QueryTerm /
QueryTermAssoc))
QueryTermAssoc = %x28 QueryTerm *(LogicalOp QueryTerm) %x29 ;
(QueryTerm)
QueryTerm = Attribute
QueryTerm =/ Attribute Operator ComparableValue
QueryTerm =/ Attribute equal CompEqualityValue
QueryTerm =/ Attribute unequal CompEqualityValue
QueryTerm =/ Attribute patternOp RegExp
QueryTerm =/ Attribute notPatternOp RegExp
Attribute = LinkedEntityRelation
LinkedEntityRelation = AttrName %x7B LinkedEntityPath %x7D          ;
AttrName{LinkedEntityPath}
LinkedEntityRelation =/ ValuePath
LinkedEntityPath = *1(EntityType 1*(%x2C EntityType) %x3A) AttrName %x7B
LinkedEntityPath %x7D
;*1(EntityType 1*(,EntityType):)AttrName{LinkedEntityPath}
LinkedEntityPath =/ ValuePath
ValuePath = DottedPath *1(%x5B DottedPath %x5D)                     ; DottedPath
*1([DottedPath])
DottedPath = AttrName *(%x2E AttrName) ; AttrName *(.AttrName)
Operator = equal / unequal / greaterEq / greater / lessEq / less
ComparableValue = Number / quotedStr / dateTime / date / time
OtherValue = false / true
Value = ComparableValue / OtherValue
Range = ComparableValue dots ComparableValue
ValueList = Value 1*(%x2C Value) ; Value 1*(, Value)
CompEqualityValue = OtherValue / ValueList / Range / URI
equal = %x3D %x3D ; ==
unequal = %x21 %x3D ; !=
greater = %x3E ; >
greaterEq = %x3E %x3D ; >=
less = %x3C ; <
lessEq = %x3C %x3D ; <=
patternOp = %x7E %x3D ; ~=
notPatternOp = %x21 %x7E %x3D ; !~=
dots = %x2E %x2E ; ..
TermChar = unicodeNumber / unicodeLetter
TermChar =/ %x5F ; _
AttrName = unicodeLetter *TermChar
EntityType = unicodeLetter *TermChar
quotedStr = String ; "*char"
andOp = %x3B ; ;
orOp = %x7C ; |
LogicalOp = andOp / orOp

unicodeNumber is any Unicode character that has Number as a Category [22]. With Unicode-capable regular expression (RegEx) parsers, such a character may be matched by \p{N}.
unicodeLetter is any Unicode character that has Letter as a Category [22]. With Unicode-capable regular expression (RegEx) parsers, such a character may be matched by \p{L}.
Number shall be a number as mandated by the JSON Specification, following the ABNF Grammar, production rule named number, section 6 of IETF RFC 8259 [6].
String shall be a text string as mandated by the JSON Specification, following the ABNF Grammar, production rule named String, section 7 of IETF RFC 8259 [6].
char shall be a character as mandated by the JSON Specification, ABNF Grammar, production rule named char, section 7 of IETF RFC 8259 [6].
false shall be conformant with the JSON ABNF Grammar, production rule named false, section 3 of IETF RFC 8259 [6]. It is intended to represent the Boolean value corresponding to false.
true shall be conformant with the JSON ABNF Grammar, production rule named true, section 3 of IETF RFC 8259 [6]. It is intended to represent the Boolean value corresponding to true.
RegExp shall be a regular expression as mandated by IEEE 1003.2™ [11].
dateTime shall be a DateTime value as mandated by clause 4.6.3.
time shall be a Time value as mandated by clause 4.6.3.
date shall be a Date value as mandated by clause 4.6.3.
URI shall be a URI as mandated by IETF RFC 3986 [5] or an IRI as mandated by IETF RFC 3987 [23], appendix A, production rule named URI.

A Query Term (production rule QueryTerm) defines a predicate which serves as a matching condition for Entities. The constituent parts of a Query Term are:

an attribute path (production rule named Attribute).
an optional pair composed by an operator (production rule named Operator) and a value (production rule named Value).

The attribute path (production rule Attribute) is a simple name AttrName, optionally followed by a dot-separated list of more AttrName (see later example 8), optionally followed by one trailing list of more dot-separated AttrNames enclosed in one pair of square brackets (see later example 9). The attribute path is always a composition of short hand names and not a fully qualified ones, because, when the query language is used, an @context properly defining all the terms (as per clause 5.5.7) shall be issued.

EXAMPLE 0:

?q=temperature (checks for the existence of the attribute temperature).

EXAMPLE 1:

?q=temperature==20 .

EXAMPLE 2:

?q=brandName!=“Mercedes” .

EXAMPLE 3:

?q=isParked==“urn:ngsi-ld:OffStreetParking:Downtown1” .

EXAMPLE 4:

A query encoded as an HTTP Query String. Note that this is HTTP binding specific, to be used via GET method, as defined in clause 6.4.3.2 . The NGSI-LD query language string is conveyed by means of parameter q .

EXAMPLE 5:

?q=isMonitoredBy (to query Entities that have the Attribute isMonitoredBy ).

Query Terms may be combined through logical operators that shall be supported by implementations as follows:

The production rule andOp defines a logical AND operator conveying that the requested entities are those which meet at the same time the conditions posed by all the Query Terms affected by such an operator.
The production rule orOp defines a logical OR operator conveying that the requested entities are those which meet any of the conditions posed by the Query Terms affected by such an operator.
When evaluating logical conditions, and in the absence of specific Query Term associations (see below), the logical AND operator shall take precedence over the logical OR operator.

Association of Query Terms shall be supported by implementations as per the grammar included by the present clause (production rule named QueryTermAssoc). An association of Query Terms is composed of the combination of different Query Terms linked by logical operators (AND, OR) and delimited by parenthesis. The evaluation of an association of Query Terms shall always take precedence over individual, non-associated Query Terms.

EXAMPLE 6:

?q=((speed>50|rpm>3000);brandName==“Mercedes”)

EXAMPLE 7:

?q=(temperature>=20;temperature<=25)|capacity<=10

The following example 8 shows the syntax of an attribute path that is defined by the production rule Attribute, as a dot-separated list of names. Such a list is intended to address a Property or Relationship included by the matching entities subjacent graph, in accordance with the following rules:

Every name in the list shall be expanded to a URI (Fully Qualified Name) as mandated by clause 5.5.7.
The first name shall refer to a Property or Relationship (top level element) whose subject shall be a matching Entity. Strictly speaking, and as per the JSON-LD representation rules, such (fully qualified) name shall be equal to the (fully qualified) name of the concerned Property or Relationship.
Each other name (if present) represents a (sub)Property or (sub)Relationship, starting with the top-level element as subject and continuing through the graph traversal. The element addressed by the last name in the list is defined as the target element. If only one name is present in the attribute path, then the target element is the top level one.

EXAMPLE 8:

?q=temperature.observedAt>=2017-12-24T12:00:00Z

If the target element is a Property, the target value is defined as the Value associated to such Property. If a Property has multiple instances (identified by its respective datasetId), and no datasetId is explicitly addressed, the target value shall be any Value of such instances.

If the target element is a LanguageProperty, and no target language is specified, the target value is defined as a value from any of the key-value pairs held within the languageMap associated to such LanguageProperty.

If the target element is a ListProperty, the target value is defined as the valueList array associated to such a ListProperty.

If the target element is a LanguageProperty and a target language is specified, the target value is defined as the Value associated to the matching key-value pair held within the languageMap associated to such LanguageProperty where the key matches the target language.

If the target element is a VocabProperty, the target value shall be expanded according to the @context.

If the target element is a Relationship, the target object is defined as the object associated (represented as a URI or array of URIs) to such Relationship. If a Relationship has multiple instances (identified by its respective datasetId), and no datasetId is explicitly addressed, the target object shall be any object of such instances.

If the target element is a ListRelationship, the target object is defined as the array of objects associated (represented as URIs) to such ListRelationship.

When a Query Term only defines an attribute path (production rule named Attribute), the matching Entities shall be those which define the target element (Property or a Relationship), regardless of any target value or object.

Lastly, implementations shall support queries involving specific data subitems belonging to a Property Value (seed target value) represented by a JSON object structure (compound value). For that purpose, an attribute path may additionally contain a trailing path (enclosed in a single pair of square brackets that signal that the overall path is now entering the compound value) composed of a dot-concatenated list of JSON member names, and intended to address a specific data subitem (member) within the seed target value. When such a trailing path is present, implementations shall interpret and evaluate it (against the seed target value) as a MemberExpression of ECMA 262 [21], in dot notation, as clarified therein at section Property Accessors). If the evaluation of such MemberExpression does not result in a defined value, the target element shall be considered as non-existent for the purpose of query resolution.

EXAMPLE 9:

?q=address[city]==“Berlin” . The trailing path is [city] . It is used to refer to a particular subitem within the value of the address Property , which is a complex JSON object representing a postal address. Refer to the following NGSI-LD Entity:

{
  "id": "urn:ngsi-ld:placedescription:123",
  "type": "PlaceDescription",
  "address": {
    "type": "Property",
    "value": {
      "city": "Berlin",
      "street": "Ulrich Strasse"
    }
  }
}

EXAMPLE 10:

?q=sensor.rawdata[airquality.particulate]==40 . The trailing path is [airquality.particulate]. The particulate Property of the compound JSON object is targeted. Refer to the following NGSI-LD Entity:

{
  "id": "urn:ngsi-ld:particulatemeasurement:345",
  "type": "ParticulateMeasurement",
  "sensor": {
    "type": "Property",
    "value": 40,
    "rawdata": {
      "type": "Property",
      "value": {
        "airquality": {
          "particulate": 40,
          "PM20": 85
        }
      }
    }
  }
}

EXAMPLE 11:

?q=parkingTickets[value]==“Overstay 60 minutes”&jsonKeys=parkingTickets . The trailing path is parkingTickets . The parkingTickets Property of the JSON object is targeted, but the target value raw is JSON, and is not expanded to ngsi-ld:hasValue using the core @context . Refer to the following NGSI-LD Entity:

{
  "id": "urn:ngsi-ld:Car:6152s",
  "type": "Car",
  "parkingTickets": {
  "type": "JsonProperty",
  "json": {
         "id": "85a6cc52-0589-45f9",
         "value": "Overstay 60 minutes"
      }
  }
}

EXAMPLE 12:

?q=gender==Male&expandValues=gender . The trailing path is gender . The gender Property of JSON object is targeted, but the target value is first expanded to a URI using the supplied @context . Refer to the following NGSI-LD Entity:

{
  "id": "urn:ngsi-ld:Person:678",
  "type": "Person",
  "gender": {
    "type": "VocabProperty",
    "vocab": "Male",
    }
  },
  @context": {
    "Male": "http://example.org/Male",
  }
}

The filter can also apply to a Property or Relationship of an NGSI-LD Entity targeted by a (recursively) followed Relationship, for example as part of a linked entity retrieval (clause 4.5.23).

EXAMPLE 13:

?q=sensor{humidity}==40 . The trailing path is sensor{humidity} . The query targets entities with a sensor Relationship and makes a sub-query on matching target objects which have the matching humidity Attribute. Refer to the following NGSI-LD Entities:

{
  "id": "urn:ngsi-ld:WeatherStation:123",
  "type": "WeatherStation",
  "sensor": {
    "type": "Relationship",
     "objectType": "Device",
    "object": "urn:ngsi-ld:Device:345"
  }
}
{
  "id": "urn:ngsi-ld:Device:345",
  "type": "Device",
  "humidity": {
    "type": "Property",
    "value": 40
  }
}

As not knowing the Entity Type targeted by a Relationship could make the query significantly more expensive, a hint for the required Entity Type can be provided, so only such NGSI-LD Entities need to be considered.

EXAMPLE 14:

?q=sensor{Device:humidity}==40 . The trailing path is sensor{Device:humidity} . The query targets entities with a sensor.entityType = “Device” within a Relationship and then makes a sub-query on matching target objects which have the matching humidity Attribute. The entityType hint results in a faster lookup. Refer to the following NGSI-LD Entities.

{
  "id": "urn:ngsi-ld:WeatherStation:123",
  "type": "WeatherStation",
  "sensor": {
    "type": "Relationship",
     "objectType": "Device",
    "object": "urn:ngsi-ld:Device:345"
  }
}
{
  "id": "urn:ngsi-ld:Device:345",
  "type": "Device",
  "humidity": {
    "type": "Property",
    "value": 40
  }
}

If the target element corresponds to a Relationship or ListRelationship, the combination of such target element with any operator different than equal or unequal shall result in not matching.

A Query Term value shall be any of the following (depending on the operator used):

A literal value (string, number, date, etc.) (production rule named Value).
A range of values (production rule named Range), specified as a minimum and a maximum value.
A regular expression (production rule named RegExp).
A URI (production rule named URI).
A comma-separated list of literal values (production rule named ValueList).

When comparing dates or times, the order relation considered shall be a temporal one.

When it comes to comparing text strings, implementations:

shall follow the recommendations defined by IETF RFC 8259 [6], section 8.3.
should support the Unicode Collation Algorithm (UCA), as defined by [13].

URI comparison should be performed so that the number of false negatives is minimized, as recommended by IETF RFC 3986 [5], section 6.

The semantics of the different logical operators used by Query Terms are described as follows and shall be supported by compliant implementations:

Existence (only attribute is specified). A matching entity shall contain the target element.
Equal operator (production rule named equal). A matching Entity shall contain the target element and meet any of the following conditions:

The Query Term value, e.g. color==“red”:

Is identical or equivalent to the target value (e.g. matches “red”).
Is included in the target value, if the latter is an array (e.g. matches [“blue”,“red”,“green”]).

If the Query Term value is a list of values (production rule named ValueList), e.g. color==“black”, “red”:

The target value is identical or equivalent to any of the list values (e.g. matches “red”).
The target value includes any of the Query Term values, if the target value is an array (e.g. matches [“red”,“blue”]).

If the Query Term value is a range (production rule named Range), e.g. temperature==10..20:

The target value is in the interval between the minimum and maximum of the range (both included) (e.g. matches 15).

The Query Term value target element corresponds to a LanguageProperty and a natural language is specified e.g. color[en]==“red”:

a match is found as the value of the key-value pair corresponding to the specified natural language of the languageMap (e.g. matches {“fr”: “rouge”, “en”: “red”,“de”: “rot”} but not {“fr”: “red”, “en”: “black”,“de”: “blue”}).
a match is found as a single element from the array of values of the key-value pair corresponding to the specified natural language of the languageMap (e.g. matches {“fr”: [“chat”, “rouge”], “en”: [“red”, “cat],”de”: [“rote”, “Katze”]} but not {“fr”: [“chat”, “rouge”], “en” : [“coal”, “black”],“de”: [“blaue”, “Engel”]}).

The Query Term value target element corresponds to a LanguageProperty and no natural language is specified e.g. color[*]==“red”:

any match is found in the values of the key-value pairs of the languageMap (e.g. matches {“fr”: “rouge”, “en”: “red”, “de”: “rote”}.
a match is found as a single element of the array of values of the key-value pairs of the languageMap (e.g. matches {“fr”: “chat”, “rouge”], “en”: [“red”, “cat”], “de”: [“rote”, “Katze”]}).

The Query Term value is a URI and the target element corresponds to a Relationship,aListRelationshipor aVocabProperty, e.g. color==“http://example/red”:

Is identical to the target value (e.g. matches “http://example.com/red”).
Is included in the target value, if the latter is an array (e.g. matches [“http://example.com/blue”,” http://example.com/red”,” http://example.com/green”]).

If the Query Term value target element corresponds to a Relationship,aListRelationshipor a VocabProperty and is a list of URIs (production rule named ValueList), e.g. color==” http://example/black”,“http://example/red”:

The target value is identical to any of the list values (e.g. matches “http://example.com/red”).
The target value includes any of the Query Term values, if the target value is an array (e.g. matches [“http://example.com/red”, “http://example.com/blue”]).

If there is no equality between the target value data type and the Query Term value data type, then it shall be considered as not matching.

Unequal operator (production rule named unequal). A matching entity shall contain the target element and meet any of the following conditions:

The Query Term value, e.g. color!=“red”:

Is neither identical nor equivalent to the target value (e.g. matches “black”).
Is not included in the target value, if the latter is an array (e.g. matches [“blue”,“black”,“green”], but not [“blue”,“red”,“green”]).

If the Query Term value is a list of values (production rule named ValueList), e.g. color!= “black”, “red”:

The target value is neither identical nor equivalent to any of the list values (e.g. matches “blue”).
The target value does not include any of the list values, if the target value is an array (e.g. matches [“blue”,“yellow”,“green”], but not [“blue”,“red”,“green”]).

If the Query Term value is a range (production rule named Range), e.g. temperature!=10..20:

The target value is not in the interval between the minimum and the maximum (both included) (e.g. matches 9).

The Query Term value target element corresponds to a LanguageProperty and a natural language is specified e.g. color[en]!=“red”:

No matching value is found as the value of the specified language key of a languageMap where a language filter is specified. (e.g. matches {“fr”: “noir”, “en”: “black”,“de”: “schwarz”} but not {“fr”: “rouge”, “en” : “red”,“de”: “rot”}).
No matching value is found as a single element from the array of values of the key-value pair corresponding to the specified natural language of the languageMap (e.g. matches {“fr”: [“chat”, “rouge”], “en”: [“coal”, “black”], “de”: [“blaue”, “Engel”]} but not {“fr”: [“rouge”, “noir”], “en” : [“red”, “black”],“de”: [“rot”, “schwarz”]}).

The Query Term value target element corresponds to a LanguageProperty and no language filter is specified e.g. color[*]!=“red”:

No matching value is found in any of the values of the key-value pairs of a languageMap (e.g. matches {“fr”: “noir”, “en”: “black”,“de”: “schwarz”}, but not {“fr”: “rouge”, “en”: “red”,“de”: “rot”}).
No matching value is found as a single element from the array of values of the key-value pair corresponding to the specified natural language of the languageMap (e.g. matches {“fr”: [“chat”, “rouge”], “en”: [“coal”, “black”], “de”: [“blaue”, “Engel”]} but not {“fr”: [“rouge”, “noir”], “en”: [“red”, “black”],“de”: [“rot”, “schwartz”]}).

The Query Term value is a URI and the target element corresponds to a Relationship,aListRelationshipora VocabProperty, e.g. color!=“http://example.com/red”:

Is not identical to the target value (e.g. matches “http://example.com/black”).
Is not included in the target value, if the latter is an array (e.g. matches [“http://example.com/blue”, “http://example.com/black”, “http://example.com/green”], but not [“http://example.com/blue”, “http://example.com/red”, “http://example.com/green”]).

If the Query Term value target element corresponds to a Relationship,aListRelationshipor a VocabProperty and is a list of URIs e.g. color!=“http://example.com/black”, ” http://example.com/red”:

The target value is not identical to any of the list values (e.g. matches “http://example.com/blue”).
The target value does not include any of the list values, if the target value is an array (e.g. matches [“http://example.com/blue”, “http://example.com/yellow”, “http://example.com/green”], but not [“http://example.com/blue”, “http://example.com/red”, “http://example.com/green”]).

If the data type of the target value and the data type of the Query Term value are different, then they shall be considered unequal.

Greater than operator (production rule named greater). For an entity to match, it shall contain the target element and the target value has to be strictly greater than the Query Term value:

If there is no equality between the target value data type and the Query Term value data type then it shall be considered as not matching.

Less than operator (production rule named less). For an entity to match, it shall contain the target element and the target value shall be strictly less than the value:

If there is no equality between the target value data type and the Query Term value data type then it shall be considered as not matching.

Greater or equal than (production rule named greaterEq). A matching entity shall meet any of the Greater than or the Equal conditions for single values.
Less or equal than (production rule named lessEq). A matching entity shall meet any of the Less than or the Equal conditions for single values.
Match pattern (production rule named patternOp). A matching entity shall contain the target element and the target value shall be in the L(R) of the regular pattern specified by the Query Term:

If the target value data type is different than String then it shall be considered as not matching.

Do not match pattern (production rule named notPatternOp). A matching entity shall contain the target element and the target value shall not be in the L(R) of the regular pattern specified by the Query Term:

If the target value data type is different than String then it shall be considered as not matching.

4.10 NGSI-LD Geoquery Language

The NGSI-LD Geoquery language shall be supported by implementations. It is intended to define predicates which allow testing whether a specific topological spatial relationship exists between a pair of geometries: a target geometry and a reference geometry. The target geometry represents a geospatial Property of an Entity, typically, the location of the Entity.

A total of four parameters are defined in order to fully specify an NGSI-LD Geoquery:

georel, to express the desired geospatial relationship;
geometry, to express the type of the reference geometry;
coordinates, to express the reference geometry;
geoproperty, to express the target geometry of an Entity. This parameter is optional, location is the default.

The following grammar defines the syntax for the geospatial relationships (parameter name georel):

andOp = %x3B ; ;
equal = %x3D %x3D ; ==
georel = nearRel / withinRel / containsRel / overlapsRel / intersectsRel
/ equalsRel / disjointRel
nearRel = nearOp andOp distance equal PositiveNumber ;
near;max(min)Distance==x (in meters)
distance = "maxDistance" / "minDistance"
nearOp = "near"
withinRel = "within"
containsRel = "contains"
intersectsRel = "intersects"
equalsRel = "equals"
disjointRel = "disjoint"
overlapsRel = "overlaps"

PositiveNumber shall be a non-zero positive number as mandated by the JSON Specification. Thus, it shall follow the ABNF Grammar, production rule named Number, section 6 of IETF RFC 8259 [6], excluding the ‘minus’ symbol and excluding the number 0.

Reference geometries shall be specified by:

A geometry type (parameter name geometry) as defined by the GeoJSON specification (IETF RFC 7946 [8], section 1.4), except GeometryCollection.
A coordinates (parameter name coordinates) element which shall represent the coordinates of the reference geometry as mandated by IETF RFC 7946 [8], section 3.1.1.

Target geometry, i.e. the target Entity’s GeoProperty to which the geoquery is to be applied, can be specified by an extra parameter named geoproperty. The GeoProperty’s name shall be specified as short hand name and not a fully qualified one, because, when the query language is used, an @context properly defining all the terms (as per clause 5.5.7) shall be issued. If no geoproperty is specified, the geoquery is applied to the default Property location (see clause 4.7.1).

Note that proper URL encoding shall be used by HTTP binding API clients when using these examples.

EXAMPLE 1:

?georel=near;maxDistance==2000

&geometry=Point
&coordinates=[8,40]
&geoproperty=observationSpace

EXAMPLE 2:

?georel=within

&geometry=Polygon
&coordinates=[[[100.0,0.0],[101.0,0.0],[101.0,1.0],[100.0,1.0],
[100.0,0.0]]]
&geoproperty=location

EXAMPLE 3:

A query encoded as an HTTP Query String. Note that this is HTTP binding specific, to be used via GET method, as defined in clause 6.4.3.2 .

&geometry=Point
&coordinates=[8,40]

The semantics of the different geospatial relationships defined above is as follows, and shall be supported by compliant implementations:

near statement (production rule named nearRel):

maxDistance modifier. For an entity to match it has to be within the buffer geometric object (as defined by [14]) given by the reference geometry, with distance (in meters) equal to the number conveyed (production rule named PositiveNumber).
minDistance modifier. For an entity to match it has to be disjoint with the buffer geometric object (as defined by [14]) given by the reference geometry, with distance (in meters) equal to the number conveyed (production rule named PositiveNumber).

equals relationship (production rule named equalsRel). For an entity to match, the target geometry shall be equal, as specified by [14], to the reference geometry.
disjoint relationship (production rule named disjointRel). For an entity to match, the target geometry shall be disjoint, as specified by [14], to the reference geometry.
intersects relationship (production rule named intersectsRel). For an entity to match, the target geometry shall intersect, as specified by [14], with the reference geometry.
within relationship (production rule named withinRel). For an entity to match, the target geometry shall be within, as specified by [14], the reference geometry.
contains relationship (production rule named containsRel). For an entity to match, the target geometry shall contain, as specified by [14], the reference geometry.
overlaps relationship (production rule named overlapsRel). For an entity to match, the target geometry shall overlap, as specified by [14], the reference geometry.

When resolving geo-queries, Entities which do not convey the target GeoProperty of the query shall be considered as non-matching.

4.11 NGSI-LD Temporal Query Language

The NGSI-LD Temporal Query language shall be supported by implementations. It is intended to define predicates which allow testing whether Temporal Properties of NGSI-LD Entities, Properties and Relationships, are within certain temporal constraints. In particular it can be used to request historic Property values and Relationships that were valid within the specified timeframe.

The following grammar defines the syntax that shall be supported:

timerel = beforeRel / afterRel / betweenRel
beforeRel = "before"
afterRel = "after"
betweenRel = "between"

The points in time for comparison are defined as follows:

A timeAt parameter, which shall represent the comparison point for the before and after relation and the starting point for the between relation. It shall be represented as DateTime (mandated by clause 4.6.3).
An endTimeAt parameter, which is only used for the between relation and shall represent the end point for comparison. It shall be represented as DateTime (mandated by clause 4.6.3).

The Temporal Property (see clause 4.8) to which the temporal query is to be applied can be specified by timeproperty. If no timeproperty is specified, the temporal query is applied to the default Temporal Property observedAt.

EXAMPLE 1:

?timerel=before&timeAt=2017-12-13T14:20:00Z

EXAMPLE 2:

?timerel=between&timeAt=2017-12-13T14:20:00Z&endTimeAt=2017-12-13T14:40:00Z&timeproperty=modifiedAt

EXAMPLE 3:

Temporal query encoded as HTTP Query String, note that this is HTTP binding specific, to be used via GET method, as defined in clause 6.18.3.2 .

&timeproperty=observedAt
&timeAt=2017-12-13T14:20:00Z

The semantics of the different temporal relations defined above is as follows, and shall be supported by compliant implementations:

before relationship (production rule named beforeRel). For a Temporal Property to match, the value of the specified Temporal Property (or observedAt as default) has to be before the time specified by timeAt. The specified value is used as an exclusive bound in the Temporal Query;
after relationship (production rule named afterRel). For a Temporal Property to match, the value of the specified Temporal Property (or observedAt as default) has to be after the time specified by timeAt. The specified value is used as an inclusive bound in the Temporal Query;
between relationship (production rule named betweenRel). For a Temporal Property to match, the value of the specified Temporal Property (or observedAt as default) has to be after the time specified by timeAt and before the time specified by endTimeAt. In the Temporal Query, the value specified for the lower bound of the range is inclusive and the value specified for the upper bound of the range is exclusive.

When resolving temporal queries, Entities which do not convey the target Temporal Property of the query shall be considered as non-matching.

4.12 NGSI-LD Pagination

NGSI-LD operations can potentially return a result set including a large number of NGSI-LD Elements, so that pagination of query results shall be supported by compliant implementations.

The list of operations that incur this behaviour is as follows:

Query Entities (clause 5.7.2).
Query Subscriptions (clause 5.8.4).
Query Context Source Registrations (clause 5.10.2).
Query Context Source Registration Subscriptions (clause 5.11.5).
Query Temporal Evolution of Entities (clause 5.7.4).

Nonetheless, the NGSI-LD API is agnostic about specific pagination mechanisms and only defines the behaviour that shall be observed by NGSI-LD Systems.

For each operation above, NGSI-LD Systems shall:

provide a mechanism to iterate through the NGSI-LD Elements of a result set without exhausting NGSI-LD Client or Broker resources;
provide a mechanism to flag NGSI-LD Clients when there are remaining NGSI-LD Elements to be traversed as part of a result set;
allow NGSI-LD Clients specifying a limit (page size), as a parameter of API operations, to the number of NGSI-LD Elements (at a maximum) retrieved by the implementation for each pagination iteration;
define a default limit (default page size) to the number of NGSI-LD Elements retrieved per pagination iteration;
allow NGSI-LD Clients iterating forwards and backwards through a result set.

NGSI-LD implementations should:

avoid Denial of Service attacks or other potential security risks, by defining a hard limit to the size of generated response payload body while paginating. For instance, certain queries can be rejected by issuing an error of type TooManyResults.

NGSI-LD implementations may:

warn NGSI-LD Clients when result sets become invalid due to dynamic changes in NGSI-LD Elements (additions, deletions) occurred while iterating over pages.

The concrete realization of the features described above might depend on each API binding. Nonetheless, NGSI-LD Systems shall implement pagination features as mandated by the present clause, for any API binding.

4.13 Counting the Number of Results

Given that NGSI-LD Query operations can potentially return a result set including a large number of NGSI-LD Elements and that pagination of query results shall be supported (see clause 4.12), compliant implementations shall also support a mechanism for relaying to the client the number of expected resulting elements, when a query is executed.

A specific field (e.g. a custom header in the response in case of HTTP binding, see clause 6.3.13) shall be returned within the response of a query, whenever this is requested by the client.

Mechanisms for limiting the number of returned NGSI-LD Elements are independent of the counting mechanism, so that, potentially, a client can issue a query that limits to zero the number of desired results but asks for the count to be present.

This is useful for client-side planning and fine-tuning of subsequent queries and their parameters.

4.14 Supporting Multiple Tenants

The concept of a Tenant is that a user or group of users utilizes a single instance of an NGSI-LD system (Context Source or Context Broker) in isolation from other users or groups of users of the same instance, which are considered to be different Tenants. Thus a multi-tenant NGSI-LD system is a system where a single software instance is used by different users or groups of users, the Tenants, where any information related to one Tenant (e.g. Entities, Subscriptions, Context Source Registrations) are only visible to users of the same Tenant, but not to users of a different Tenant. Typically, multi-tenancy is used together with an access control mechanism, enforcing the isolation of Tenants, however access control and other security-related aspects are out-of-scope of the present document.

The NGSI-LD API optionally enables multi-tenant systems. To support this, Tenant information can be optionally specified in NGSI-LD API operations. The operation then only applies to the targeted Tenant. As all information of one Tenant is isolated from other Tenants, the NGSI-LD API operations for managing, retrieving and subscribing to entity information, but also any context source related operations only apply to the information of the specified Tenant in isolation and never have any effect on the information of other Tenants.

As the support and use of Tenants is optional, any operation not explicitly specifying a Tenant targets a default Tenant, which always exists. NGSI-LD systems not supporting multiple Tenants should raise an error of type NoMultiTenantSupport if a Tenant is specified. To enable Context Sources to be part of tenant-based distributed or federated systems, Tenant information can optionally be specified in Context Source Registrations. When contacting the respective Context Sources, the Tenant information from the Context Source Registration has to be used. If no Tenant information is present in the Context Source Registration, no Tenant information is to be used and thus the default Tenant is targeted on the registered Context Source. This enables integrating Context Sources not supporting multi-tenancy in a distributed system with a Tenant-based Context Broker or integrating local Tenants in a federated system using a different Tenant.

4.15 NGSI-LD Language Filter

The NGSI-LD Language Filter shall be supported by implementations. It is intended to form a mechanism which allows just one matching string value of LanguageProperties of NGSI-LD Entities to be converted to an NGSI-LD Property, where the value will be a string for the specified natural language.

The following grammar defines the syntax that shall be supported by the filter:

lang = langtag

Where the langtag is defined according to the rules as mandated by IETF RFC 5646 [28], and IETF RFC 3282 [29]. If the Context Broker cannot serve any matching language, it shall default to any supported language. This behaviour can be triggered by specifying lang=“*”in the filter (see example 3).

In any case, the attribute in question shall be augmented with an additional non-reified subproperty lang indicating the actual language returned.

EXAMPLE 1:

Specified natural language - return LanguageProperties as strings in English only.

lang=“en”

EXAMPLE 2:

Multiple natural languages with no ranked preference - return LanguageProperties as strings in either Swiss French or French.

lang=“fr-CH,fr”

EXAMPLE 3:

Wildcard - return LanguageProperties as a string in any supported language.

lang=“*”

EXAMPLE 4:

Quality value ranking - return all LanguageProperties as a string in Swiss French or French with no ranked preference, fallback to English as a second choice and finally fallback to any other supported language.

lang=“fr-CH,fr;q=0.9,en;q=0.8,*;q=0.5”

4.16 Supporting Multiple Entity Types

From NGSI-LD API version 1.5.1 onwards, multiple Entity Types for any Entity are supported. An Entity is uniquely identified by its id, so whenever information is provided for an Entity with a given id, it is considered part of the same Entity, regardless of the Entity Type(s) specified. To avoid unexpected behaviour, Entity Types can be implicitly added by all operations that update or append attributes. There is no operation to remove Entity Types from an Entity. The philosophy here is to assume that an Entity always had all Entity Types, but possibly not all Entity Types have previously been known in the system. The only option to remove an Entity Type is to delete the Entity and re-create it with the same id. Alternatively, a batch upsert with ‘replace’ update mode can be used, as described in clause 5.6.8.

4.17 NGSI-LD Entity Type Selection Language

The NGSI-LD Entity Type Selection Language shall be supported by implementations. It is intended to select only those Entities that have the specified Entity Type(s), possibly among others. Entity Types are specified as a disjunction of elements, where each element can either directly be an Entity Type or a conjunction of multiple Entity Types. The logical operators are the same as in the NGSI-LD Query Language specified in clause 4.9. As a disjunction of Entity Types can also be seen as a list, and to be compatible with previous versions of the NGSI-LD API, a comma can be used as an alternative representation of the or operator. For logical and grouping parenthesis are needed.

EntityTypes = OrEntityType *(orOp OrEntityType)         ; OrEntityType|OrEntityType
OrEntityType = %x28 EntityType *(andOp EntityType) %x29             ; (EntityType;EntityType)
OrEntityType = EntityType                               ; EntityType
andOp = %x3B                                ; ;
orOp = %x7C / %x2C                                                  ; |  ,

EntityType is either a valid name as specified in clause 4.6.2 or a URI.

EXAMPLE 1:

Entities of type Building or House:

Building|House

Building,House

EXAMPLE 2:

Entities of type Home and Vehicle:

(Home;Vehicle)

EXAMPLE 3:

Entities of type (Home and Vehicle) or Motorhome:

(Home;Vehicle)|Motorhome

(Home;Vehicle),Motorhome

NOTE:

The special characters “,” , “;” , “(” and “)” used in the Entity Type Selection Language are allowed characters in URIs. The use of short names is recommended.

4.18 NGSI-LD Scopes

An NGSI-LD Scope enables putting Entities into a hierarchical structure and restrict results of queries and notifications accordingly. The hierarchical structure is user-defined, e.g. according to (logical) location or organization. The use of Scopes is optional and an Entity can be assigned to one or more Scopes at the same time. The Scope is represented as a special scope Property that is non-reified in the normalized Entity representation and reified in the temporal representation of an Entity. In the latter case, it is restricted to having the non-reified Temporal Properties createdAt, modifiedAt and deletedAt as sub-Properties. There shall at most be one instance of the scope property per Entity. In case multiple representations of the same Entity have to be merged, e.g. when combining the results of distributed queries, the values of scope are merged. The value of scope is represented as a JSON array in case there is more than one Scope. For the Temporal Evolution a given Scope is considered valid from the time it has been set until the time it has been explicitly removed by an update or delete operation (for an example see annex C, clause C.5.16).

The grammar that encodes the syntax of the Scope is expressed in ABNF format [12]. It is described below (it has been validated using <https://github.com/ietf-tools/bap>), and it shall be supported by implementations. The special string “urn:ngsi-ld:null” (i.e. the NGSI-LD Null) shall be only used and only appear in case of deleted scopes.

Scope = [%x2F] ScopeLevel *(%x2F ScopeLevel)              ; [/] ScopeLevel *(/ScopeLevel)
Scope =/ "urn:ngsi-ld:null"                               ; the literal string "urn:ngsi-ld:null"
ScopeLevel = unicodeLetter *ScopeLevelChar
ScopeLevelChar = unicodeNumber / unicodeLetter
ScopeLevelChar =/ %x5F                                    ; _

EXAMPLE 1:

/Madrid

EXAMPLE 2:

Madrid

EXAMPLE 3:

/Madrid/Gardens/ParqueNorte

EXAMPLE 4:

/CompanyA/OrganizationB/UnitC

4.19 NGSI-LD Scope Query Language

The NGSI-LD Scope Query Language shall be supported by implementations. It is intended to select only those Entities that are within the specified Scope(s). Scopes are specified as a disjunction of elements, where each element can either directly be a Scope or a conjunction of multiple Scopes. The “+” can be used as a wildcard to match a single scope level within a Scope. The “#” that can be added at the end of a Scope specification serves as a wildcard, which matches the given scope and the whole hierarchy of scopes below. The “/#” matches any non-empty scope, i.e. only explicitly specified scopes. The logical operators are the same as in the NGSI-LD Query Language specified in clause 4.9. As a disjunction of Scopes can also be seen as a list, a comma can be used as an alternative representation of the or operator. For logical and grouping parenthesis are needed.

ScopesQ = OrScopeQ *(orOp OrScopeQ)         ; OrScopeQ|OrScopeQ
ScopesQ =/ %x2F %23             ; / #
OrScopeQ = %x28 ScopeQ *(andOp ScopeQ) %x29                 ; (ScopeQ;ScopeQ)
OrScopeQ =/ ScopeQ *1(%x2F %23)                             ; ScopeQ / #
andOp = %x3B                                ; ;
orOp = %x7C / %x2C                                                  ; |  ,
ScopeQ = %x2F ScopeQLevel *(%x2F ScopeQLevel)                       ; /ScopeQLevel *(/ScopeQLevel)
ScopeQLevel = unicodeLetter *ScopeQLevelChar
ScopeQLevel =/ %x2B             ; + 
ScopeQLevelChar = unicodeNumber / unicodeLetter
ScopeQLevelChar =/ %x5F                                             ; _

EXAMPLE 1:

Scope /Madrid:

/Madrid

EXAMPLE 2:

Scope /Madrid/Gardens and the whole scope tree below:

/Madrid/Gardens/#,
/Madrid/Gardens, /Madrid/Gardens/ParqueNorte, /Madrid/Gardens/ParqueNorte/Parterre1, /Madrid/Gardens/ParqueSur

EXAMPLE 3:

Scopes /Madrid/Gardens/ParqueNorte and /Madrid/Sights/ParqueNorte, or any other Scope with Madrid as first scope level and ParqueNorte as third scope level:

/Madrid/+/ParqueNorte

EXAMPLE 4:

Scope /Madrid/Districts and /CompanyA:

(/Madrid/Districts;/CompanyA)

EXAMPLE 5:

Scope (/Madrid/Districts and /CompanyA) or /CompanyB:

(/Madrid/Districts;/CompanyA)|CompanyB

(/Madrid/Districts;/CompanyA),CompanyB

4.20 NGSI-LD Distributed Operation names

When registering Context Sources (see clause 5.2.9), the registrant NGSI-LD interface endpoint may optionally offer a subset of NGSI-LD operations which it accepts. Table 4.20‑1 defines a list of names for each of these operations.

Table 4.20-1: Names of implemented Operations

Operation name	Implements
Context Information Provision	createEntity	5.6.1 Create Entity
	updateEntity	5.6.2 Update Attributes
	appendAttrs	5.6.3 Append Attributes
	updateAttrs	5.6.4 Partial Attribute update
	deleteAttrs	5.6.5 Delete Attribute
	deleteEntity	5.6.6 Delete Entity
	createBatch	5.6.7 Batch Entity Creation
	upsertBatch	5.6.8 Batch Entity Creation or Update (Upsert)
	updateBatch	5.6.9 Batch Entity Update
	deleteBatch	5.6.10 Batch Entity Delete
	upsertTemporal	5.6.11 Create or Update Temporal Evolution of an Entity
	appendAttrsTemporal	5.6.12 Add Attributes to Temporal Evolution of an Entity
	deleteAttrsTemporal	5.6.13 Delete Attributes from Temporal Evolution of an Entity
	updateAttrInstanceTemporal	5.6.14 Partial Update Attribute Instance in Temporal Evolution of an Entity
	deleteAttrInstanceTemporal	5.6.15 Delete Attribute Instance from Temporal Evolution of an Entity
	deleteTemporal	5.6.16 Delete Temporal Evolution of an Entity
	mergeEntity	5.6.17 Merge Entity
	replaceEntity	5.6.18 Replace Entity
	replaceAttrs	5.6.19 Replace Attribute
	mergeBatch	5.6.20 Batch Entity Merge
	purgeEntity	5.6.21 Purge Entities
Context Information Consumption	retrieveEntity	5.7.1 Retrieve Entity
	queryEntity	5.7.2 Query Entities (excluding batch entity queries)
	queryBatch	5.7.2 Query Entities (batch entity queries only)
	retrieveTemporal	5.7.3 Retrieve Temporal Evolution of an Entity
	queryTemporal	5.7.4 Query Temporal Evolution of Entities
	retrieveEntityTypes	5.7.5 Retrieve Available Entity Types
	retrieveEntityTypeDetails	5.7.6 Retrieve Details of Available Entity Types
	retrieveEntityTypeInfo	5.7.7 Retrieve Available Entity Type Information
	retrieveAttrTypes	5.7.8 Retrieve Available Attributes
	retrieveAttrTypeDetails	5.7.9 Retrieve Details of Available Attributes
	retrieveAttrTypeInfo	5.7.10 Retrieve Available Attribute Information
Context Information Subscription	createSubscription	5.8.1 Create Subscription
	updateSubscription	5.8.2 Update Subscription
	retrieveSubscription	5.8.3 Retrieve Subscription
	querySubscription	5.8.4 Query Subscription
	deleteSubscription	5.8.5 Delete Subscription
Support operations for distributed operations	retrieveEntityMap	5.14.1 Retrieve EntityMap
	updateEntityMap	5.14.2 Update EntityMap
	deleteEntityMap	5.14.3 Delete EntityMap
	createEntityMapQueryEntity	5.14.4 Create EntityMap for Query Entities
	createEntityMapQueryTemporal	5.14.5 Create EntityMap for Query Temporal Evolution of Entities
	retrieveContextSourceIdentity	5.15.1 Retrieve Context Source Identity Information

In addition to these individual operations, a series of names for common groups of operations have also been defined. Table 4.20‑2 defines a list of names for each of these operation groups.

Table 4.20-2: Named Operation Groups

Operation Group name	Implements
federationOps	retrieveEntity queryEntity queryBatch retrieveEntityTypes retrieveEntityTypeDetails retrieveEntityTypeInfo retrieveAttrTypes retrieveAttrTypeDetails retrieveAttrTypeInfo createSubscription updateSubscription retrieveSubscription querySubscription deleteSubscription retrieveEntityMap updateEntityMap deleteEntityMap createEntityMapQueryEntity retrieveContextSourceIdentity
associationOps
updateOps	updateEntity updateAttrs replaceEntity replaceAttrs
retrieveOps	retrieveEntity queryEntity
redirectionOps	createEntity updateEntity appendAttrs updateAttrs deleteAttrs deleteEntity mergeEntity replaceEntity replaceAttrs retrieveEntity queryEntity purgeEntity retrieveEntityTypes retrieveEntityTypeDetails retrieveEntityTypeInfo retrieveAttrTypes retrieveAttrTypeDetails retrieveAttrTypeInfo retrieveEntityMap updateEntityMap deleteEntityMap createEntityMapQueryEntity retrieveContextSourceIdentity

If no specific subset of operations is defined for a Context Source Registration, the default set of operations matches the group defined as “federationOps”.

4.21 NGSI-LD Attribute Projection Language

The NGSI-LD Attribute Projection Language shall be supported by implementations for projection parameters (e.g. pick and omit). Its aim is to specify the Attributes to be retrieved within an Entity (or associated Linked Entities when Linked Entity Retrieval is used). Projected Attributes are specified as a disjunction of elements, where each element can either directly be an Attribute name, or in the case of Linked Entity Retrieval, a Relationship name followed by an Attribute name within the Linked Entity. Since a disjunction of Attributes is a list, either a comma or a pipe character can be used as alternative representations of the or operator. In the following, ABNF grammar for NGSI-LD Attribute Projection Language is given.

orOp = %x7C / %x2C                                                  ; |  ,
ProjectionTerm = AttrName *1(LinkedEntityTerm) *(orOp ProjectionTerm)
LinkedEntityTerm  = %x7B ProjectionTerm %x7D        ; {ProjectionTerm}

See clause 4.9 for the definition of AttrName.

EXAMPLE 1:

?pick=temperature

EXAMPLE 2:

?pick=temperature,humidity

EXAMPLE 3:

?pick=observation{temperature,humidity}

4.22 Transient Storage of Entities and Attributes

In some cases, it is desirable to create an Entity (or Attribute) which is only expected to be stored for a defined period of time. Thereafter such an Entity (or Attribute) should be removed, and can be safely deleted from the context via an automatic garbage collection process.

In this regard NGSI-LD defines the following system Property of type TemporalProperty that shall be supported by implementations:

expiresAt is defined as the system temporal Property at which a certain Entity, Property or Relationship shall become invalid and may be automatically removed from the Context Broker. For example, an Alert Entity was created to last for 24 hours and should be removed after this period of time.

It should be noted that clean-up processes will only run periodically, and will be dependent upon the Context Broker implementation, therefore final deletion will always lag the expiresAt timestamp to a certain extent. Furthermore, expiresAt only applies to the local storage, i.e. the Entity or Attribute is to be deleted locally, but not on other Context Sources or Context Broker hosting such Entity information, where no expiresAt timestamp is present. Thus expiresAt is not considered to be intrinsic to the Entity or Attribute, but only applies to the storage of the Entity or Attribute respectively. As it pertains to a system function (the deletion from storage after the expiration time), it is considered to be a system attribute.

4.23 Entity Ordering

4.23.1 Introduction

When a Context Consumer queries for Entities retrieved from a single context broker, it shall be possible to request that the array of Entities returned are ordered according to the values held within an Entity Attribute. Context Broker implementations shall interpret such requests and return the array of Entities sorted accordingly.

For each Attribute name listed, one of four types of sort order can be specified:

Sort in ascending order by target value or target object
Sort in descending order by target value or target object
Sort by distance in ascending order from a specified GeoJSON geometry
Sort by distance in descending order from a specified GeoJSON geometry

When sorting by ascending or descending order, the preferred sort order for numbers and datetimes is trivial, however for strings the default collation order shall be defined as using ICU “root” collation order (“und-x-icu”) which returns a reasonable language-agnostic sort order (see IETF RFC 6067 [36]).

Sort by distance shall be limited to GeoProperties, and shall be defined as calculating spherical distance using the Haversine formula.

Sort ordering is never applied to distributed operations, and the defined sort ordering strategy may depend on implementation specific configurations.

4.23.2 Datatype Comparison Order

When sorting by value, and the values of Attributes are of mixed datatypes, the following comparison order (null values last), shall be implicitly applied:

Numbers
Strings
Object
Array
Boolean
Time
Date
DateTime
Null
Attribute does not exist

Additionally, when sorting by distance, the following comparison order, shall be applied:

Attribute is a GeoProperty
Attribute is not a GeoProperty - sorted by value as shown above.

4.23.3 NGSI-LD Entity Ordering Language

The NGSI-LD Entity Ordering Language shall be supported by implementations for the order parameter (i.e. orderBy). Its aim is to specify the Attributes to be used when ordering an Array of Entities retrieved. Ordering Attributes are specified as a disjunction of elements, where each element can either directly be an Attribute name, or an Attribute name followed by a direction (either ascending or descending, where ascending shall be the default if not supplied). The comma character shall be used to separate the elements to be used for ordering which shall be applied sequentially.

In the following, ABNF grammar for NGSI-LD Entity Ordering Language is given.

thenOp = %x2C                                                       ; ,
directionOp ::= asc | desc | dist-asc|
dist-desc
OrderingTerm = AttrName *1(DirectionTerm) *(thenOp OrderingTerm)
DirectionTerm = %x3B directionOp.                                   ; ;

See clause 4.9 for the definition of AttrName.

EXAMPLE 1:

?orderBy=name - applies sort ordering to rank Entities in ascending order using the value of the name Attribute.

EXAMPLE 2:

?orderBy=name,age - applies sort ordering to rank Entities in ascending order using the value of the name Attribute and thereafter where multiple Entities have the same name , by ascending order using the age Attribute.

EXAMPLE 3:

?orderBy=name,age;desc - applies sort ordering to rank Entities in ascending order using the value of the name Attribute and thereafter where multiple Entities have the same name , by descending order using the value of age Attribute.

EXAMPLE 4:

?orderBy=address[city] - applies sort ordering using a sub-item within a Property Value defined as a complex JSON object. The trailing path is [city] . It is used to refer to a particular subitem within the value of the address Property .

EXAMPLE 5:

?orderBy=name.observedAt - applies sort ordering based on an attribute path that is defined by the production rule Attribute , as a dot-separated list of names. Such a list is intended to address a Property or Relationship included by the matching entities subjacent graph.

When sorting data using a specific ICU collation order as defined by IETF RFC 6067 [36], the collation element (parameter name collation) shall represent the preferred ordering.

EXAMPLE 6:

?orderBy=name&collation=und-u-ks-identic - applies sort ordering to rank Entities in ascending order using the case insensitive value of the name Attribute.

EXAMPLE 7:

?orderBy=name&collation=de-u-co-phonebk - applies sort ordering to rank Entities in ascending order using the value of the name Attribute and sorted according to German phonebook collation ordering.

For sort by distance, the coordinates element (parameter name orderFrom) shall represent the coordinates of the reference geometry as mandated by IETF RFC 7946 [8], section 3.1.2.

EXAMPLE 8:

?orderBy=location;dist-asc&orderFrom=[8,40] - applies sort ordering to rank Entities in ascending distance from a Point with respect to the location GeoProperty .

EXAMPLE 9:

?orderBy=location;dist-desc&orderFrom=[8,40] - applies sort ordering to rank Entities in descending distance from a Point with respect to the location GeoProperty .

EXAMPLE 10:

?orderBy=location;dist-asc

&orderFrom=[[8,40],[9,42],[9,45],[8,40]]
&orderGeometry=LineString