4 Context Information Management Framework

4.1 Introduction

This 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:

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:

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 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 clause 4.3.3 and clause 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 Entitiesand 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 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 Sourcesand managing Context Source Registrations(CSRs)
5.9.2 Register Context Source
5.9.3 Update CSR
5.9.4 Delete CSR
Context SourceDiscovery - operations for retrieving and discovering CSRs
5.7.1 Retrieve CSR
5.7.2 Query CSRs
Context Source RegistrationSubscription - 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
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 JSONLDContext API is 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
Registry API
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

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 Entities

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

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 every Context 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 relates to specific Attributes found on a single Entity. Thus, the registration shall define both:

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

Potentially multiple distinct redirect registrations can apply at the same time. The Context Broker itself 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 Source are 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:

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 Source could 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 Source shall endeavour to amend its payload accordingly. Table 4.3.6.7‑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.7‑2 describes conformance fallbacks for an NGSI-LD Property (and its subclasses) and Table 4.3.6.7‑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[]1
1.0
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
expiresAt
String
DateTime as mandated by clause 4.22
1.9
Remove attribute from payload
<Property name>
Property
or Property[]2
Property as mandated by clause 4.5.2.
1.0
GeoProperty or GeoProperty[]2
GeoProperty as mandated by clause 4.5.2.
1.0
LanguageProperty or LanguageProperty[]2
LanguageProperty as mandated by clause 4.5.18.
1.4
Reformat attribute as Property
JsonProperty or JsonProperty[]2
JsonProperty as mandated by clause 4.5.24.
1.8
Reformat attribute as Property
VocabProperty or VocabProperty[]2
VocabProperty as mandated by clause 4.5.20.
1.8
Reformat attribute as Property
ListProperty or ListProperty[]1
ListProperty as mandated by clause 4.5.21.
1.8
Reformat attribute as Property
<Relationship name>
Relationship
or Relationship[]3
Relationship as mandated by clause 4.5.3.
1.0
ListRelationship or ListRelationship[]3
ListRelationship as mandated by clause 4.5.22.
1.8
Reformat attribute as Relationship
NOTE 1:
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:
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:
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 atrribute 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 flexibile 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.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:

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

The user @context shall not contain JSON-LD Scoped Contexts (see [2], section 4.1.8), as described in clause 5.5.7.

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

Optional

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

Optional

System Generated

Output Only

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

Prohibited

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

Prohibited

During partial update patch and merge patch (see clauses 5.5.8 and 5.5.12), when deleting a Property without a datasetId, as well as when notifying about a deleted Property without sub-attributes, the NGSI-LD Property should be represented in a concise representation by a member whose key is the Property name (a term) and whose value is "urn:ngsi-ld:null".

An NGSI-LD Property which includes 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 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) including the following members:

Mandatory

Optional

System Generated

Output Only

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

Prohibited

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

Optional

System Generated

Output Only

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

Prohibited

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

Optional

System Generated

Output Only

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

Prohibited

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

Optional

EXAMPLE 1:
"name": "David Robert Jones"
EXAMPLE 2:
2:
"name": {
  "dataset": {
    "@none": "David Robert Jones",
    "urn:ngsi-ld:datasetId:001": "David Bowie",
    "urn:ngsi-ld:datasetId:002": "Ziggy Stardust"
  }
}
EXAMPLE 3:
"location": {"type": "Point", "coordinates": [13.3986, 52.5547]}
EXAMPLE 4:
"says": {"languageMap": {"en": "yes", "fr": "oui"}
EXAMPLE 5:
5:
"parkingTickets": {
  "json": {
     "id": "85a6cc52-0589-45f9",
     "value": "Overstay 60 minutes"
  }
}
EXAMPLE 6:
"gender": {"vocab": "Male"}
EXAMPLE 7:
" provi d edBy ": "urn:ngsi-ld: Device :31415 "
EXAMPLE 8:
8:
"devices": [
     "urn:ngsi-ld:Device:14142",
     "urn:ngsi-ld:Device:13562", 
     "urn:ngsi-ld:Device:37309"
]
EXAMPLE 9:
9:
"providedBy": {
  "id": "urn:ngsi-ld:Device:31415",
  "type": "Device",
  "brandName": "Anemometer",
  "manufacturerName": "Cyberdyne Systems",
  "windSpeed": 60
}
EXAMPLE 10:
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
    }
]
EXAMPLE 11:
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:
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
    }
]
EXAMPLE 13:
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"
  }
}
EXAMPLE 14:
"periods": ["First", "Second", "Third", "Fourth"]
EXAMPLE 15:
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"]
  }
}
EXAMPLE 16:
16:
"route":[
  "urn:ngsi-ld:BusStop:0101",
  "urn:ngsi-ld:BusStop:0102",
  "urn:ngsi-ld:BusStop:9912"
]
EXAMPLE 17:
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]}
  }
]
EXAMPLE 18:
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]}
  }
]
EXAMPLE 19:
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 datasetId can 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 Source and 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 differenciate:

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

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:

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, 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 [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, 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 [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

Optional

EXAMPLE 1:
1:
"name": {
  "type": "Property",
  "values": [
    [
      "Joe Bloggs",
      "2022-08-09T18:25:02Z"
    ],
    [
      "Bill Smith",
      "2022-08-10T18:25:02Z"
    ]
  ]
}
EXAMPLE 2:
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"
    ]
  ]
}
EXAMPLE 3:
3:
"period": {
  "type": "ListProperty",
  "valueLists": [
    [
      ["First", "Second", "Third", "Fourth"],
      "2022-08-09T18:25:02Z"
    ],
    [
      ["1st", "2nd", "3rd", "4th"],
      "2022-08-10T18:25:02Z"
    ]
  ]
}
EXAMPLE 4:
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"
    ]
  ]
}
EXAMPLE 5:
5:
"gender": {
  "type": "VocabProperty",
  "vocabs": [
    [
      {"vocab": "Male"},
      "2022-08-09T18:25:02Z"
    ],
    [
      {"vocab": "Female"},
      "2022-08-10T18:25:02Z"
    ]
  ]
}
EXAMPLE 6:
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:
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"
    ]
  ]
}
EXAMPLE 7:
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

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

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

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

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

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

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

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

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

Optional

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

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

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

Prohibited

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

Optional

Output Only

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

Prohibited

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:

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

1) the value obtained after applying the aggregation method over the period;
2) the start DateTime of the corresponding period;
3) the end DateTime of the corresponding period.
1) the value obtained after applying the aggregation method over the period;
2) the start DateTime of the corresponding period;
3) 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:

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

The values supported by the aggrMethods parameter are the following:

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)
totalCount
Calculate the number of times the value has been updated inside the period
distinctCount
Calculate the count of distinct 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
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
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
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
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
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
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
totalCount
Calculate the number of times the value has been updated inside the period
distinctCount
Calculate the count of distinct values inside the period
sum
N/A
N/A
N/A
N/A
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
min
Calculate the minimum value inside the period
Calculate the minimum value inside the period
Calculate the minimum value inside the period
N/A
max
Calculate the maximum value inside the period
Calculate the maximum value inside the period
Calculate the maximum value inside the period
N/A
stddev
N/A
N/A
N/A
N/A
sumsq
N/A
N/A
N/A
N/A
Table 4.5.19.1-3: Semantics of aggregation methods for Relationships
Aggregation Method
Relationship
totalCount
Calculate the number of times the relationship has been updated inside the period
distinctCount
Calculate the count of distinct relationships targets inside the period
sum
N/A
avg
N/A
min
N/A
max
N/A
stddev
N/A
sumsq
N/A

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

Output Only

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

Prohibited

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

Optional

Output Only

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

Prohibited

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

Output Only

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

Prohibited

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

Optional

Output Only

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

Prohibited

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

Output Only

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

Prohibited

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

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

Optional

Output Only

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

Prohibited

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

Output Only

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

Prohibited

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

Optional

Output Only

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

Prohibited

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

Optional

Output Only

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

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:

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

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

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:

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:

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:

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.

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

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:

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:

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

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://tools.ietf.org/tools/bap/abnf.cgi), 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

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:

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:

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:

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

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

When it comes to comparing text strings, implementations:

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:

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:

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:

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:

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:

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:

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:

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:

NGSI-LD implementations should:

NGSI-LD implementations may:

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 behavior 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://tools.ietf.org/tools/bap/abnf.cgi), and it shall be supported by implementations:

Scope = [%x2F] ScopeLevel *(%x2F ScopeLevel)                        ; [/] ScopeLevel *(/ScopeLevel)
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/#, e.g. matches the following Scopes:
/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
  • retrieveEntity
  • queryEntity
  • queryBatch
  • retrieveEntityTypes
  • retrieveEntityTypeDetails
  • retrieveEntityTypeInfo
  • retrieveAttrTypes
  • retrieveAttrTypeDetails
  • retrieveAttrTypeInfo
  • createSubscription
  • updateSubscription
  • retrieveSubscription
  • querySubscription
  • deleteSubscription
  • retrieveContextSourceIdentity
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:

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.