Intellectual Property Rights

IPRs essential or potentially essential to normative deliverables may have been declared to ETSI. The declarations pertaining to these essential IPRs, if any, are publicly available for ETSI members and non-members, and can be found in ETSI SR 000 314: "Intellectual Property Rights (IPRs); Essential, or potentially Essential, IPRs notified to ETSI in respect of ETSI standards", which is available from the ETSI Secretariat. Latest updates are available on the ETSI IPR online database.

Pursuant to the ETSI Directives including the ETSI IPR Policy, no investigation regarding the essentiality of IPRs, including IPR searches, has been carried out by ETSI. No guarantee can be given as to the existence of other IPRs not referenced in ETSI SR 000 314 (or the updates on the ETSI Web server) which are, or may be, or may become, essential to the present document.

The present document may include trademarks and/or tradenames which are asserted and/or registered by their owners. ETSI claims no ownership of these except for any which are indicated as being the property of ETSI, and conveys no right to use or reproduce any trademark and/or tradename. Mention of those trademarks in the present document does not constitute an endorsement by ETSI of products, services or organizations associated with those trademarks.

DECT™, PLUGTESTS™, UMTS™ and the ETSI logo are trademarks of ETSI registered for the benefit of its Members. 3GPP™, LTE™ and 5G™ logo are trademarks of ETSI registered for the benefit of its Members and of the 3GPP Organizational Partners. oneM2M™ logo is a trademark of ETSI registered for the benefit of its Members and of the oneM2M Partners. GSM^® and the GSM logo are trademarks registered and owned by the GSM Association.

Foreword

This Technical Specification (TS) has been produced by ETSI Technical Committee Data Solutions (TC DATA).

Modal verbs terminology

In the present document "should", "should not", "may", "need not", "will", "will not", "can" and "cannot" are to be interpreted as described in clause 3.2 of the ETSI Drafting Rules (Verbal forms for the expression of provisions).

"must" and "must not" are NOT allowed in ETSI deliverables except when used in direct citation.

Executive summary

The present document formally describes the abstract part of the NGSI-LD API specification, independent of any particular binding to protocols supporting the operations of the API. The binding of the API operations to the HTTP protocol is defined in [i.16]. The NGSI-LD API allows users to provide, consume and subscribe to context information in multiple scenarios and involving multiple stakeholders. Context information is modelled as attributes (properties and relationships) of context entities, also referred to as "digital twins", representing real-world assets. It enables close to real-time access to information coming from many different sources (not only IoT data sources).

Introduction

The present document defines the NGSI-LD API Specification. The NGSI-LD API allows users to provide, consume and subscribe to context information in multiple scenarios and involving multiple stakeholders. Context information is modelled as attributes of context entities, also referred to as "digital twins", representing real-world assets (e.g. a bus in a city or a luggage claim ticket). Because of that, the NGSI-LD API is often used to bring standardized access to digital twin data.

The ongoing status of the NGSI-LD API can be found in [i.1]. The binding of the API operations to the HTTP protocol is defined in [i.16].

The ETSI TC DATA has decided to use the name "NGSI-LD API". The rationale is to reinforce the fact that the present document leverages on the former OMA NGSI 9 and 10 interfaces [i.2] and FIWARE^® NGSIv2 [i.3] to incorporate the latest advances from Linked Data.

The NGSI-LD API and information model benefited from contributions developed in the context of the following research projects:

• No. 101136799 (MARCLAIMED)
• No. 101180452 (URBAQUANTUM)
• No. 101270878 (DYNACITY)
• No. 101081802 (CONSERWA)
• No. G69J18001180007 (Data Highway)
• No. FTE0000471 (GeminiPort)
• No. PE00000001 (DUSTAR, RESTART SPOKE 6)
• No. 101069732 (aerOS)
• No. 101135784 (ARISE)
• No. 101189589 (O-CEI)

and from contributions developed by members of the FIWARE^® Community.

1 Scope

The present document defines a standardized API for context information management (NGSI-LD API), enabling close to real-time (right-time) access to context information/digital twins coming from many different sources (not only IoT data sources). The present document defines how such an API enables applications to perform updates on context, register context sources which can be queried to get updates on context, query information on current and historic context information and subscribe to receive notifications of context changes. The criteria for choice of the API characteristics are based on requirements resulting from the Use Cases ETSI GR CIM 002 [i.4] and other work items ETSI GR CIM 007 [i.5] (security) and ETSI TS 104 178 [i.6] (information model). The present document supersedes prior versions, including ETSI GS CIM 009 [i.7] and ETSI GS CIM 004 [i.8].

2 References

2.1 Normative references

References are either specific (identified by date of publication and/or edition number or version number) or non-specific. For specific references, only the cited version applies. For non-specific references, the latest version of the referenced document (including any amendments) applies.

Referenced documents which are not found to be publicly available in the expected location might be found in the ETSI docbox.

The following referenced documents are necessary for the application of the present document.

2.2 Informative references

References are either specific (identified by date of publication and/or edition number or version number) or non-specific. For specific references, only the cited version applies. For non-specific references, the latest version of the referenced document (including any amendments) applies.

The following referenced documents may be useful in implementing an ETSI deliverable or add to the reader's understanding, but are not required for conformance to the present document.

3 Definition of terms, symbols and abbreviations

3.1 Terms

For the purposes of the present document, the following terms apply:

NGSI-LD Attribute: reference to both an NGSI-LD Property and to an NGSI-LD Relationship

NGSI-LD Attribute Instance (in the case of temporal representation of NGSI-LD Entities): reference to an NGSI-LD Attribute, at a specific moment in time of its temporal evolution, usually identified by its instanceId

NGSI-LD Central Broker: NGSI-LD Context Broker that only uses a local storage when serving NGSI-LD requests, without involving any external Context Sources

NGSI-LD Context Broker: architectural component that implements all the NGSI-LD interfaces

NGSI-LD Context Consumer: agent that uses the query and subscription functionality of NGSI-LD to retrieve context information

NGSI-LD Context Producer: agent that uses the NGSI-LD context provision and/or registration functionality to provide or announce the availability of its context information to an NGSI-LD Context Broker

NGSI-LD Context Registry: software functional element where Context Sources register the information that they can provide

NGSI-LD Context Source: source of context information which implements the NGSI-LD consumption and subscription (and possibly provision) interfaces defined by the present document

NGSI-LD Context Source Registration: description of the information that can be provided by a Context Source, which is used when registering the Context Source with the Context Registry

NGSI-LD Core API: core part of the NGSI-LD API that has to be implemented by all Brokers, including operations for providing or managing Entities and Attributes, operations for consuming Entities and checking which Entity Types and Attributes Entities are available in the system and operations for subscribing to Entities, receiving notifications and managing subscriptions

NGSI-LD Distribution Broker: NGSI-LD Context Broker that uses both local context information and registration information from an NGSI-LD Context Registry, to access matching context information from a set of distributed Context Sources

NGSI-LD Element: any JSON element that is defined by the NGSI-LD API

NGSI-LD Entity: informational representative of something that is supposed to exist in the real world, physically or conceptually

NGSI-LD Entity Map: mapping of NGSI-LD Entity ids to Context Source Registrations used in maintaining atomicity of transactions performed by Distribution Brokers and Federation Brokers

NGSI-LD Entity Type: categorization of an NGSI-LD Entity as belonging to a class of similar entities, or sharing a set of characteristic properties

NGSI-LD External Linked Entity: Linked Entity that is identified through a dereferenceable URI which does not exist within the current NGSI-LD system

NGSI-LD Federation Broker: Distribution Broker that federates information from multiple underlying NGSI-LD Context Brokers and across domains

NGSI-LD GeoProperty: subclass of NGSI-LD Property which is a description instance which associates a main characteristic, i.e. an NGSI-LD Value, to either an NGSI-LD Entity, an NGSI-LD Relationship or another NGSI-LD Property, that uses the special hasValue property to define its target value and holds a geographic location in GeoJSON format

NGSI-LD Internal Linked Entity: Linked Entity that exists within the current NGSI-LD system

NGSI-LD JSONLDContext API: part of the NGSI-LD API that is used to host, serve and manage JSON-LD @contexts

NGSI-LD JsonProperty: subclass of NGSI-LD Property which is a description instance which associates a raw JSON literal value as a defined main characteristic to an NGSI-LD Entity, an NGSI-LD Relationship or another NGSI-LD Property and that uses the special hasJson (a subproperty of hasValue) property to define its target value

NGSI-LD LanguageProperty: subclass of NGSI-LD Property which is a description instance which associates a set of strings in different natural languages as a defined main characteristic, i.e. an NGSI-LD Map, to an NGSI-LD Entity, an NGSI-LD Relationship or another NGSI-LD Property and that uses the special hasLanguageMap (a subproperty of hasValue) property to define its target value

NGSI-LD Linked Entity: NGSI-LD Entity referenced from another NGSI-LD Entity (the linking NGSI-LD Entity) via an NGSI-LD Relationship

NGSI-LD Linking Entity: NGSI-LD Entity which is the subject of a Relationship to another NGSI-LD Entity (the NGSI-LD Linked Entity) or an external resource (identified by a URI)

NGSI-LD ListProperty: description instance which associates an ordered array of main characteristics, i.e. NGSI-LD Values, to either an NGSI-LD Entity, an NGSI-LD Relationship or another NGSI-LD Property, and that uses the special hasValueList property to define its target value

NGSI-LD ListRelationship: description of an ordered array of directed links between a subject, which is either an NGSI-LD Entity, an NGSI-LD Property or another NGSI-LD Relationship, on one hand, and a series of objects, which are NGSI-LD Entities, on the other hand, and which uses the special hasObjectList property to define its target objects

NGSI-LD Map: JSON-LD language map in the form of key-value pairs holding the string representation of a main characteristic in a series of natural languages

NGSI-LD Null: "urn:ngsi-ld:null" or {"@none": "urn:ngsi-ld:null"} used as an encoding for null values

NGSI-LD Property: description instance which associates a main characteristic, i.e. an NGSI-LD Value, to either an NGSI-LD Entity, an NGSI-LD Relationship or another NGSI-LD Property and that uses the special hasValue property to define its target value

NGSI-LD Query: collection of criteria used to select a sub-set of NGSI-LD Elements, matching the criteria

NGSI-LD Registry API: part of the NGSI-LD API that is implemented by the Context Registry, including operations for registering Context Sources and managing Context Source Registrations (CSRs), operations for retrieving and discovering CSRs, and operations for subscribing to CSRs and receiving notifications

NGSI-LD Relationship: description of a directed link between a subject which is either an NGSI-LD Entity, an NGSI-LD Property or another NGSI-LD Relationship, on one hand, and an object, or an unordered array of objects, each of which is an NGSI-LD Entity, on the other hand, and which uses the special hasObject property to define its target object

NGSI-LD Scope: hierarchical structuring of Entities that enables restricting query results and notifications

NGSI-LD Snapshot: set of NGSI-LD Entities, retrieved through one or more NGSI-LD Queries, which are locally persisted, providing a relatively consistent view of the situation when the queries were executed, and on which Context Consumers can execute further local NGSI-LD Operations

NGSI-LD Temporal API: part of the NGSI-LD API pertaining to the Temporal Evolution of Entities, including operations for providing and managing the Temporal Evolution of Entities and Attributes, and operations for consuming the Temporal Evolution of Entities

NGSI-LD Temporal Evolution of an Entity: sequence of values attributed to an NGSI-LD Entity over time, i.e. its history or future predictions

NGSI-LD Tenant: user or group of users that utilize a single instance of a system implementing the NGSI-LD API (NGSI-LD Context Source or NGSI-LD Broker) in isolation from other users or groups of users of the same instance, so that 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

NGSI-LD Value: JSON value (i.e. a string, a number, true or false, an object, an array), or JSON-LD typed value (i.e. a string as the lexical form of the value together with a type, defined by an XSD base type or more generally an IRI), or JSON-LD structured value (i.e. a set, a list, a language-tagged string)

NGSI-LD VocabProperty: subclass of NGSI-LD Property, which is a description instance which associates a string value, which can be coerced to a URI, as a defined main characteristic to an NGSI-LD Entity, an NGSI-LD Relationship or another NGSI-LD Property and that uses the special hasVocab (a subproperty of hasValue) property to define its target value

3.2 Symbols

Void.

3.3 Abbreviations

For the purposes of the present document, the following abbreviations apply:

4 NGSI-LD conceptual overview informative

4.1 Introduction

Clause 4 gives an introduction to the technical design principles behind the context information management framework supported by NGSI-LD. It provides an overview of the information model, architectural assumptions and supported architectures, the representation in JSON-LD, and a high-level overview of the API and its most important features. The clause is informative as it provides an overview only, leaving out many details. The goal is to put the reader into a better position to understand the following normative clauses that provide all the details of the NGSI-LD API.

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 E for details.

4.2 NGSI-LD information model

4.2.1 Introduction

The NGSI-LD Information Model specifies the structure of context information to be supported by an NGSI-LD system. It is defined in ETSI TS 104 178 [i.6]. It specifies the data representation mechanisms to 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 (Graph Databases [i.9]). 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.10] 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 shown in the present document is a minimal one, aimed at defining the classes used in this release of the API specification. It has been extended in ETSI TS 104 178 [i.6], with classes defining extra concepts such as mobile vs. stationary entities, instantaneous vs. static properties, etc.

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: Model concept	Description
	[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 is 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.

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

• An NGSI-LD Entity is a subclass of rdfs:Resource (RDF Schema 1.1 [i.11]).
• An NGSI-LD Relationship is a subclass of rdfs:Resource (RDF Schema 1.1 [i.11]).
• An NGSI-LD Property is a subclass of rdfs:Resource (RDF Schema 1.1 [i.11]).
• An NGSI-LD Value is either a rdfs:Literal or a node object (in JSON-LD syntax) to represent complex data structures (RDF Schema 1.1 [i.11]).
• An NGSI-LD Property has a value, stated through hasValue, which is of type rdf:Property (RDF Schema 1.1 [i.11]).
• An NGSI-LD Relationship has an object stated through hasObject which is of type rdf:Property (RDF Schema 1.1 [i.11]).

4.2.3 Cross-domain ontology

Legend: Model concept	Description
	[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 is 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 describes the concepts introduced by the NGSI-LD Cross-Domain Ontology to be supported by implementations as follows:

• Geo Properties: Are intended to convey geospatial information as defined in clause 5.2.6.4.5.
• Temporal Properties: Are non-reified Properties (represented only by their Value) that convey temporal information for capturing the time series evolution of other Properties; they are defined in clause 5.2.4.
• Language Properties: Are intended to convey different versions of the same textual values, whenever a version for each language (for instance: English, Spanish) is needed.
• "unitCode" Property: Is a Property intended to provide the units of measurement of an NGSI-LD Value as defined in clause 5.2.6.4.3.
• "scope" Property: Is a Property that enables putting Entities into a hierarchical structure as defined in clause 5.2.7.
• LanguageMaps: Are a special type of NGSI-LD Value intended to convey the different values of Language Properties, stated through an hasLanguageMap, which is of type rdf:Property (RDF Schema 1.1 [i.11]) and is itself a subproperty of hasValue.
• Geometry Values: Are a special type of NGSI-LD Value intended to convey geometries corresponding to geospatial properties as defined in clause 5.2.6.4.5.
• Time Values: Are a special type of NGSI-LD Value intended to convey time instants or intervals representations as defined in clause 5.2.2.4.

Clause 4.3.4.3 introduces 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 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".

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

The adjacentTo Relationship links entities of type "Parking" with entities of type "Street".

4.2.5 UML representation

This clause 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 (RDF Schema 1.1 [i.11]) 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.

4.3 NGSI-LD architectures

4.3.1 Introduction

Originally, the NGSI-LD API has been intended to define an API without prescribing a specific architecture and thus the NGSI-LD API can be used in different architectural settings. In the course of time, the distributed architecture has been described in more details, partially specifying interactions and behaviours of components in more details to ensure interoperability between different NGSI-LD systems, partially with recommendations on how to best implement distributed functionality for efficiency or scalability reasons.

In the following, the three main architectural setups are described, in which the NGSI-LD API is being used. Nevertheless, there may be additional architectural setups in which the NGSI-LD API can also be used. The design decisions for the NGSI-LD API take the three described architectural setups into consideration to enable the efficient and scalable operation of NGSI-LD systems. A real system architecture utilizing the NGSI-LD API can map to one, take elements from multiple or combine all of them.

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

• the "current state";
• the "temporal evolution" (both the past and possibly future predictions).

The NGSI-LD API is structured into a Core API and an optional Temporal API. The Core API manages the current state of Entities. The Temporal API is optional and manages the Temporal Evolution of Entities. NGSI-LD systems that intend to implement the Temporal API can 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.

4.3.3 Distributed and federated architectures

4.3.3.1 Introduction

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

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 Context Consumers to 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.

The federated architecture shown in Figure 4.3.3.1-2 is a variation of the distributed architecture above. It 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 are to enabled to easily access all available information using just one point of access. The architecture works in the same way as the distributed architecture, except that instead of simple Context Sources, whole domains are registered with the respective Context Broker as a point of access. Typically, the domains will be registered in the federation Context Registry at 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.

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

Context Source Registrations provide the basis for enabling distributed and federated architectures. They need to contain all the relevant information that allows Context Brokers to find the right Context Source for consuming or provisioning Context information.

To find suitable Context Sources for an NGSI-LD request, it has to be checked whether a Context Source manages potentially relevant Entity information. Thus, Context Sources specify what Entity information they manage, which is then matched with what is specified in the request. Context Source Registrations can specify Entities on different granularity levels. The highest granularity is to specify each Entity with its identifier, type and the names of available Attributes. Depending on the dynamics of the Entities stored in the Context Source this may require many updates to the respective Context Source Registration. On the other hand, the Context Source is only contacted regarding information it actually has. Further levels of granularity only provide Entity id and type. If the identifier of different Entities follow a common pattern, this pattern can be provided instead of a specific identifier, or only the Entity Type. It is also possible to specify only the names of the Attributes. If the level of granularity is coarse-grained as in the last examples, there will be few updates to the Context Source Registration, but there may be many requests for Entities that would fit according to Entity Type or Attribute Name, which are not actually available in the Context Source. Thus, the granularity level relates to a trade-off between Context Source Registration and unsuccessful requests for Entity information to Context Source.

Beyond the specification of Entities, Context Source Registrations can include additional information for filtering, e.g. a geographic area specified by coordinates in which all Entities can be found. This can be matched to queries in which a geographic filter is specified. Only in case there is an overlap, the Context Source has to be contacted.

One fundamental concept underpinning all of the prototypical architectures described above is the idea that Entity data, even regarding the same Entity, 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 indicated above, it is possible to have mixed architectures, i.e. Distribution and Federation Brokers can also store Entity information locally, as in the centralized case.

However, there are cases where some more control is needed where Entity data is stored. To enable this, there are different types of registrations:

• 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. There a two different sub-types of additive registrations:

  • 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). 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 4.4). Context data from auxiliary Context Sources is only included if it is supplementary to the context data otherwise available to the Context Broker.

• 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. There a two different sub-types of proxied registrations:

  • 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 are to be supported for the same combination of registered Attributes on the Entity. An exclusive registration always relates to specific Attributes of a single Entity.
  • A redirect Context Source Registration also specifies that the registered context data is held in a location external to the Context Broker. Redirect registrations can also refer to whole Entities or all Entities of certain Entity Types. Unlike in the exclusive case, multiple distinct redirect registrations can apply at the same time.

A more detailed specification of registration types can be found in clause 9.3.

4.3.3.3 Distributed request execution

4.3.3.3.1 Introduction

Figure 4.3.3.3.1-1 sketches the different steps of a request from a Context Consumer that requires a distributed execution. The Distribution Broker (or Federation Broker) sends a discovery request to the Context Registry. The Context Registry matches the discovery request with its Context Source Registrations and returns the fitting ones. Based on the information in the Context Source Registrations, the Distribution Broker]{.HTML-Keyboard} contacts Context Sources, forwarding adapted requests to the Context Sources. They return their results. The Distribution Broker aggregates the results, possibly retrieves additional information and filters the results, before returning the final result to the Context Consumer.

In case the request from the Context Consumer is a Subscription, the request to the Context Registry is a Context Source Registration Subscription to the Context Registry, which will send a Notification with the currently relevant Context Source Registrations. On any change regarding the relevant Context Source Registrations, it will send another Notification with the updates.

4.3.3.3.2 Matching registrations

When querying Context Source Registrations, the Entities and/or Attributes specified in the request have to be matched against the set of Context Source Registrations, extracting the matching ones.

The relevant specification information in the query for Context Source Registrations is the selector of Entity Types (if present), the list of Entity identifiers (if present), the id pattern (if present) and the list of Attribute names (if present).

At least one of the following elements has to be present: a. selector of Entity Types; or b. list of Attribute names.

There is a match, if the following conditions apply:

• If present, the selector of Entity Types, Entity identifiers and id pattern match at least one of those specified in the Context Source Registrations.
• If present, the Attribute identifiers match the Attributes (combination of Properties and Relationships) specified in the Context Source Registrations.

If a condition is not present, it is considered to apply.

The detailed conditions of matching can be found in clause 9.4.

The Context Source Registrations that have been successfully matched, are then filtered according to further conditions specified in the query, e.g. the geographic location specified in geographic coordinates. Only those matching all filter conditions are returned as a result.

4.3.3.3.3 Contacting context sources

Based on the information in the Context Source Registrations, the Distribution Broker adapts the request. Only information actually provided by the Context Source is to be retrieved, e.g. if the original requests targets Attributes a, b and c, but the Context Source, according to its Context Source Registrations, only provides a and c, then only Attributes a and c are requested.

If Entities can be distributed across multiple Context Sources, filters are not forwarded, as Entities first need to be assembled before filters can be applied. If, however, it is known that each Entity is in its entirety stored in a single Context Source, the filters can be forwarded, making the overall processing more efficient.

The adapted request can only be forwarded to the Context Sources, if the required operation is supported. If not, a possible alternative request based on a different operation or multiple requests using different operations can be used by the Distribution Broker. If there is no alternative in such a case, the overall request partially fails, as requests to other Context Sources can be successful.

In some cases, the Context Source Registration contains additional information, e.g. headers to be added. Finally, the request(s) are sent to the endpoint given in the Context Source Registration.

Additional information on what needs to be done when contacting Context Sources is specified in clause 9.5.

4.3.3.3.4 Aggregating and processing of results

The Entity information retrieved from the Context Sources is aggregated. In case individual Entities can be distributed across different Context Sources, additional retrieval steps can be necessary to ensure that the relevant Entity information is there before applying the filters. If the same Entity information is available from different Context Sources, timestamps are compared to provide the most recent one. Once all information has been aggregated and filtered, the result is returned to the Context Consumer.

4.3.4 JSON-LD

4.3.4.1 Introduction

NGSI-LD serialization is based on JSON-LD Specification [i.12], a JSON-based format for serializing Linked Data and a representation of RDF. 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 motivation is to have, on the one hand, unique terms, on the other hand, a compact, easily readable representation based on short terms. NGSI-LD defines the terms of its vocabulary in the core @context, users can define further terms relevant for their data model in a user @context, in particular the Entity Types and Attribute names they need.

4.3.4.2 Expansion and compaction

NGSI-LD API operations allow clients to use short-hand strings as non-qualified names, particularly for Attribute or Entity Type names. For instance, an API client can refer to the term "Store" as a non-qualified type name. When executing API operations where content is provided in the body, NGSI-LD systems expand terms to URIs based on a provided user @context, or, as a fall-back, on the NGSI-LD core @context, in order to obtain and store Fully Qualified Names, e.g. "https://uri.etsi.org/ngsi-ld/example/Store". The originally used short name is not stored anywhere, nor is the user @context provided as part of the request.

Likewise, when returning results, NGSI-LD systems compact URIs (Fully Qualified Names) to short terms in order to provide short-hand strings to Context Consumers, based on the user @context provided as part of the request, not any previously used user @context.

The term "URI expansion" or "compaction" is performed using an @context as described by the JSON-LD Specification [i.12], clause 5.1.

{
  "id": "urn:ngsi-ld:Store:001",
  "type": "Store",
  "storeName": {
    "type": "Property",
    "value": "Checker Market"
  }
}

{
  "@context": [
    {
      "Store": "https://uri.etsi.org/ngsi-ld/example/Store",
      "storeName": "https://uri.etsi.org/ngsi-ld/example/storeName"
    },
    "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
  ]
}

[
  {
    "@id": "urn:ngsi-ld:Store:001",
    "@type": [
      "https://uri.etsi.org/ngsi-ld/example/Store"
    ],
    "https://uri.etsi.org/ngsi-ld/example/storeName": [
      {
        "@type": [
          "https://uri.etsi.org/ngsi-ld/Property"
        ],
        "https://uri.etsi.org/ngsi-ld/hasValue": [
          {
            "@value": "Checker Market"
          }
        ]
      }
    ],
  }
]

{
  "@context": [
    {
      "Shop": "https://uri.etsi.org/ngsi-ld/example/Store",
      "shopName": "https://uri.etsi.org/ngsi-ld/example/storeName"
    },
    "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
  ]
}

{
  "id": "urn:ngsi-ld:Store:001",
  "type": "Shop",
  "shopName": {
    "type": "Property",
    "value": "Checker Market"
  }
}

4.3.4.3 Core @context

The core NGSI-LD (JSON-LD) @context is defined as a JSON-LD @context which contains:

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

NGSI-LD compliant implementations support such core @context, which is considered implicitly present when processing or generating context information. Furthermore, the core @context is protected and remains immutable and invariant during expansion or compaction of terms. Therefore, and as per the JSON-LD processing rules (JSON-LD Specification [i.12]), when processing NGSI-LD content, implementations are to 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 are expected to 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 is always treated as if it had been originally placed in the last position, so that, if needed, upstream JSON-LD processors can properly expand as NGSI-LD or override the resulting JSON-LD documents provided by API implementations.

The NGSI-LD core @context is publicly available at https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld and contains all the terms as specified in annex B.

4.3.4.4 User @context

In addition to the terms defined by the core NGSI-LD @context (as specified in annex B), a user @context is to be provided that contains the following terms:

• One term associated with the Entity Type, mapping the Entity Type name with its Type Identifier (URI).
• One term associated with the name of each Attribute or any of its subclasses, mapping the Property name with its Property Identifier (URI).

Generally, a user @context is provided with each request. However, in addition to the core @context, NGSI-LD systems can allow the specification of a user default @context that then is to be used as @context, if no user @context is provided with the request.

4.4 API overview

The NGSI-LD API provides operations to manage, find and access both the current state of Entities, as well as the Temporal Evolution of Entities. Table 4.4-1 introduces the structure of the NGSI-LD API. It is structured into the Core API, the Temporal API, the Distributed API, the Registry API, the Snapshot API and the Table 4.4-1 introduces the structure of the NGSI-LD API. It is structured into the Core API, the Temporal API, the Distributed API, the Registry API, the Snapshot API and the JSON-LDContext API. These APIs are substructured into functional groups that are further described in Table 4.4-1. Each of the functional groups consists of a number of operations, which are described in detail in clause 6.

The Distributed API includes the distributed versions of the Core API and the Temporal API operations, plus a number of supporting operations needed in the distributed case, e.g. for enabling efficient pagination across Entity information distributed across multiple Context Sources. The provided distributed functionalities are generally the same from a user perspective, but implementing them can require taking into account additional aspects, and, unlike most of their local counterparts, their execution can possibly only be partially successful.

The Registry API provides operations to manage and discover Context Sources that can be relevant to a distributed request.

The Snapshot API includes all operations related to snapshots. Snapshots allow creating a consistent (within the limits of the possibly distributed NGSI-LD system) view of the Entities selected by the queries. It allows consuming these Entities, but also using provision operations for making available predicted and simulated information, e.g. as needed for digital twins.

The JSONLDContext API implements the capability of storing and serving @contexts to clients. The stored @contexts can be managed by clients directly. Clients can store custom user @contexts at the Context Broker, effectively using the Context Broker as an @context server.

5 Context information and representation

5.1 Introduction

Clause 5 defines data structures and operations of the NGSI-LD API. No specific binding is assumed.

5.2 NGSI-LD modelling, data types and data representation

5.2.1 Introduction

Clause 5.2 describes how to represent data within NGSI-LD implementations.

5.2.2 Data representation

5.2.2.1 Introduction

Clause 5.2.2 defines the general requirements for data representation across the NGSI-LD API.

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

5.2.2.3 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                         ; Representing the underscore character _
name = unicodeLetter *nameChar

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

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

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

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

5.2.2.4 Supported data types for Values

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

• All the JSON native data types as mandated by IETF RFC 8259 [3], section 3.
• All the GeoJSON Geometries (IETF RFC 7946 n.4 with the exception of GeometryCollection.

• DateTime string for encoding a timestamp, i.e. a calendar date together with a time of day, expressed in UTC, using the ISO 8601 [5] Complete Representation and in particular using the 'Extended Format', as described below:

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

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

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

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

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

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

• The string shall not contain expressions of the difference between local time and UTC. All representations shall be interpreted as being expressed in UTC.
• URI as mandated by ISO 8601 [5], Appendix A, production rule named 'URI'.

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

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

5.2.2.5 Supported content

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

• %x3C; <
• %x3E; >
• %x22; "
• %x27; '
• %x3D; =
• %x3B; ;
• %x28; (
• %x29; )

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

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

5.2.3 Entity Types

All NGSI-LD Entities have at least one Entity Type. 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 10.3.3.

Users should name and define Entity types relevant to their own data model in a user @context. These term definitions should avoid the use of the terms already defined within the core @context, as such terms are reserved to be used as data types within the NGSI-LD Core API itself, and therefore cannot be redefined elsewhere.

GeoJSON-LD type definitions (GeoJSON-LD 1.0 [i.13]) are also defined in the core @context and reserved for use in geographic operations:

The following names are defined in the core @context and are reserved for temporal definitions:

A full list of terms defined for use by the NGSI-LD API can be discovered through reading the core NGSI-LD @context found in annex B.

5.2.4 Simple Attributes / temporal Attributes

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

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

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

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

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

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

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

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

5.2.5 Matrix of all Attributes

Table 5.2.5-1 gives a list of all attribute names used within NGSI-LD data types. The core @context provides term definitions for all of these attribute names. Where possible, users should avoid the repurposing of these attribute names when creating their own user-defined term definitions in the user @context.

Unscoped term definitions for attribute names within the core @context, can never be overridden, since the core @context definition always has priority over any user @context definition. core @context definitions for attribute names which are defined as Property-scoped or Type-scoped (as described by the JSON-LD Specification [8], section 1.4) may be overridden where necessary, although this usage is still discouraged.

Furthermore, the following additional attribute names are also defined in the core @context:

• "detail" and "title" are used in Error responses and retain their definitions from IETF RFC 7807 [6]. See clause 8.3.3.
• "avg", "distinctCount", "max", "min", "stddev", "sum", "sumsq", "totalCount" are used by the Aggregated temporal representation of an Entity. See clause 5.3.2.7.
• "bbox", "properties", "coordinates" are used in geographic operations and retain their standard GeoJSON-LD definitions (GeoJSON-LD 1.0 [i.13]).
• "dataset" is used in the representation of an Entity in the simplified format to separate the datasetId of multi-attributes. see clause 5.3.2.4
• "langString" is defined to retain its standard RDF datatype (RDF 1.1 [7]).

The full list of attribute names defined as terms can be discovered through reading the core NGSI-LD @context found in annex B.

5.2.6 Data types

5.2.6.1 Introduction

Implementations shall support the data types defined by the clauses below. For each member defined by each data type (including nested ones) a term shall be added to the core @context, as mandated by clause 5.3.2.1.

None of the members described admit a null value directly, as when a JSON-LD processor encounters null, the associated entry or value is always removed when expanding the JSON-LD document.

However, in the context of a partial update or merge operation (see clause 8.4.2 and clause 8.4.3), an NGSI-LD Null shall be used to indicate the removal of a target member, as explained in clause 8.4.3. In all other cases, implementations shall raise an error of type BadRequestData if an NGSI-LD Null value is encountered.

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

Non-normative JSON Schema Validation [i.14] definitions of the referred data types are also available at NGSI-LD JSON Schemas [i.15].

The use of URI in the context of the present document also includes the use of International Resource Identifiers (IRIs) as defined in IETF RFC 3987 [1], which extends the use of characters to Unicode characters (Unicode^® 15.0.0 [2]) beyond the ASCII character set, enabling the support of languages other than English.

5.2.6.2 Common members

The JSON-LD representation of NGSI-LD Entity, Attribute, Context Source Registration and Subscription can include the common members described by Table 5.2.6.2-1.

Those members are read-only, and shall be automatically generated by NGSI-LD implementations. They shall not be provided by Context Producers. In the event that they are provided (in update or create operations) NGSI-LD implementations shall ignore them.

In query or retrieve operations implementations shall only generate common members (Table 5.2.6.2-1) when the Context Consumer explicitly asks for their inclusion.

5.2.6.3 @context

When encoding NGSI-LD Entities, Context Source Registrations, Subscriptions and Notifications, as pure JSON-LD (MIME type "application/ld+json"), an array (flattened to a single string if necessary), containing a user @context where present, and the core @context (as described in clause 5.3.2.1) shall be included as a special member of the corresponding JSON-LD Object. Table 5.2.6.3-1 gives a precise definition of this special member.

5.2.6.4 Representational data types

5.2.6.4.1 Entity

This type represents the data needed to define an NGSI-LD Entity to be represented as in clause 5.3.

On an Entity, NGSI-LD defines the following Attributes of type GeoProperty (clause 5.2.6.4.5). Preferably, these Attribute names should be used if they semantically fit, but if necessary, additional Attribute names of type GeoProperty can be defined by Context Producers:

• "location" is defined as the geospatial Property representing the geographic location of the Entity, e.g. the location of a building or the current location of a car.
• "observationSpace" is defined as the geospatial Property representing the geographic location that is being observed, e.g. by a sensor.

• "operationSpace" is defined as the geospatial Property representing the geographic location in which an Entity, e.g. an actuator is active.

The defined GeoProperties can also be used as part of Context Source Registrations (clause 5.2.6.5.3). 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 Attribute location corresponds to the space of the city in which the location of cars is monitored.

The supported JSON members shall comply with the requirements provided in Table 5.2.6.4.1-1.

5.2.6.4.2 EntityTemporal

This datatype represents the Temporal Evolution of an Entity.

This is the same datatype as mandated by clause 5.2.6.4.1, with the only deviation that the representation of Properties and Relationships shall be the temporal one, as defined in clause 5.3.2.5. Alternatively, it is possible to specify the EntityTemporal by using the "Simplified temporal representation of an Entity", as defined in clause 5.3.2.6.

5.2.6.4.3 Property

This type represents the data needed to define an NGSI-LD Property.

The supported JSON members shall comply with the requirements provided in Table 5.2.6.4.3-1. The datatype definition defines all the required attributes for the normalized format. In the concise format, the Attribute type member can be omitted as type="Property" can be inferred from the presence of the value member. Furthermore, in the concise format of a Property, the value member cannot be a GeoJSON Object (as defined in clause 5.2.6.4.5) as it would be interpreted as a GeoProperty (see clause 5.2.6.4.5).

The following output only members (defined by Table 5.2.6.4.3-2) of the Property data structure are also defined. They are read-only and shall be generated by NGSI-LD implementations. They shall not be provided by Context Producers. In the event that they are provided (in update or create operations), NGSI-LD implementations shall ignore them.

Furthermore, a Property shall never include the following members:

Prohibited

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

5.2.6.4.4 Relationship

This type represents the data needed to define an NGSI-LD Relationship.

The supported JSON members shall comply with the requirements provided in Table 5.2.6.4.4-1. The datatype definition defines all the required attributes for the normalized format. In the concise format, the Attribute type member can be omitted, as type="Relationship" can be inferred from the presence of the object member. See clause 5.2.6.4.6.

The following output only members (defined by Table 5.2.6.4.4-2) of the Relationship data structure are also defined. They are read-only and shall be generated by NGSI-LD implementations. They shall not be provided by Context Producers. In the event that they are provided (in update or create operations), NGSI-LD implementations shall ignore them.

Furthermore, a Relationship shall never include the following members:

Prohibited

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

5.2.6.4.5 GeoProperty

This type represents the data needed to define an NGSI-LD GeoProperty.

Geospatial Properties in NGSI-LD shall be represented using GeoJSON Geometries (IETF RFC 7946 [4]). With the aim of highlighting and encoding those Properties which convey geospatial characteristics, NGSI-LD defines a special type of Property named GeoProperty.

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 (IETF RFC 7946 [4]) 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.

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 [3], meeting the syntax and restrictions mandated by IETF RFC 7946 [4] when representing a valid Geometry of the type specified.

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

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

The supported JSON members shall comply with the requirements provided in Table 5.2.6.4.5-1. The datatype definition defines all the required attributes for the normalized format. In the concise format, the Attribute type member can be omitted as type="GeoProperty" can be inferred from the presence of the value member holding a GeoJSON Geometry (IETF RFC 7946 [4]). See clause 5.2.6.4.6.

The following output only members (defined by Table 5.2.6.4.5-2) of the GeoProperty data structure are also defined. They are read-only and shall be generated by NGSI-LD implementations. They shall not be provided by Context Producers. In the event that they are provided (in update or create operations) NGSI-LD implementations shall ignore them.

In addition to the list of prohibited attribute names for a Property described in in clause 5.2.6.4.3, GeoProperties shall never include the following members:

Prohibited

• "unitCode" shall never be present, as GeoProperties are unitless.

5.2.6.4.6 LanguageProperty

This type represents the data needed to define an NGSI-LD LanguageProperty. Note that in the case of the concise format, the type can be omitted as type="LanguageProperty" can be inferred from the presence of the languageMap member. See clause 5.2.6.4.6.

The supported JSON members shall comply with the requirements provided in Table 5.2.6.4.6-1.

Note that the value of the LanguageProperty languageMap member, shall be a JSON object consisting of a series of key-value pairs where the keys shall be JSON strings representing IETF RFC 5646 [11] language codes or the JSON-LD "@none" for representing the default when no more specific language is found. The value of each key-value pair be JSON strings or arrays of JSON strings.

Additionally, the languageMap encoding {"@none": "urn:ngsi-ld:null"} shall be used to represent an NGSI-LD Null during partial update patch and merge patch (see clause 8.4.2 and clause 8.4.3) and for representing deleted Language Properties in notifications and in temporal evolutions.

The following output only members (defined by Table 5.2.6.4.6-2) of the LanguageProperty data structure are also defined. They are read-only and shall be generated by NGSI-LD implementations. They shall not be provided by Context Producers. In the event that they are provided (in update or create operations), NGSI-LD implementations shall ignore them.

In addition to the list of prohibited attribute names for a Property described in in clause 5.2.6.4.3, LanguageProperty data structures shall never include the following members:

Prohibited

• "value" and "previousValue" shall never be present, as they define a Property value, they are replaced by "languageMap" and "previousLanguageMap" respectively.
• "unitCode" shall never be present, as LanguageProperties are unitless.

5.2.6.4.7 VocabProperty

This type represents the data needed to define an NGSI-LD VocabProperty. In the case of the concise format, the type can omitted as type="VocabProperty" can be inferred from the presence of the vocab member. See clause 5.2.6.4.6.

The supported JSON members shall comply with the requirements provided in Table 5.2.6.4.7-1.

The following output only members (defined by Table 5.2.6.4.7-2) of the VocabProperty data structure are also defined. They are read-only and shall be generated by NGSI-LD implementations. They shall not be provided by Context Producers. In the event that they are provided (in update or create operations) NGSI-LD implementations shall ignore them.

In addition to the list of prohibited attribute names for a Property described in clause 5.2.6.4.3, VocabProperty data structures shall never include the following members:

Prohibited

• "value" and "previousValue" shall never be present, as they define a Property value, they are replaced by "vocab" and "previousVocab": respectively.
• "unitCode" shall never be present, as VocabProperties are unitless.

5.2.6.4.8 ListProperty

This type represents the data needed to define an NGSI-LD ListProperty. Note that in the case of the concise format, the type can be omitted as type="ListProperty" can be inferred from the presence of the valueList member. See clause 5.2.6.4.6.

The supported JSON members shall comply with the requirements provided in Table 5.2.6.4.8-1.

The following output only members (defined by Table 5.2.6.4.8-2) of the ListProperty data structure are also defined. They are read-only and shall be generated by NGSI-LD implementations. They shall not be provided by Context Producers. In the event that they are provided (in update or create operations), NGSI-LD implementations shall ignore them.

In addition to the list of prohibited attribute names for a Property described in in clause 5.2.6.4.3, ListProperty data structures shall never include the following members:

Prohibited

• "value" and "previousValue" shall never be present, as they define a Property value, they are replaced by "valueList" and "previousValueList": respectively.

5.2.6.4.9 ListRelationship

This type represents the data needed to define an NGSI-LD ListRelationship. Note that in the case of the concise format, the type can be omitted as type="ListRelationship" can be inferred from the presence of the objectList member. See clause 5.2.6.4.6.Note that the objectList may also be represented as an ordered array of Strings.

The supported JSON members shall comply with the requirements provided in Table 5.2.6.4.9-1.

The following output only members (defined by Table 5.2.6.4.9-2) of the Relationship data structure are also defined. They are read-only and shall be generated by NGSI-LD implementations. They shall not be provided by Context Producers. In the event that they are provided (in update or create operations), NGSI-LD implementations shall ignore them.

In addition to the list of prohibited attribute names for a Relationship described in in clause 5.2.6.4.4, ListRelationship data structures shall never include the following members:

Prohibited

• "object" and "previousObject" shall never be present, as they define a Relationship value, they are replaced by "objectList" and "previousObjectList": respectively.
• "entity" shall never be present, as it is used for Linked Entity retrieval of Relationship, it is replaced by "entityList".

5.2.6.4.10 JsonProperty

This type represents the data needed to define an NGSI-LD JsonProperty. Note that in the case of the concise format, the type can be omitted as type="JsonProperty" can be inferred from the presence of the json member. See clause 5.2.6.4.6.

The supported JSON members shall comply with the requirements provided in Table 5.2.6.4.10-1.

The following output only members (defined by Table 5.2.6.4.10-2) of the JsonProperty data structure are also defined. They are read-only and shall be generated by NGSI-LD implementations. They shall not be provided by Context Producers. In the event that they are provided (in update or create operations) NGSI-LD implementations shall ignore them.

In addition to the list of prohibited attribute names for a Property described in in clause 5.2.6.4.3, JsonProperty data structures shall never include the following members:

Prohibited

• "value" and "previousValue" shall never be present, as they define a Property value, they are replaced by "json" and "previousJson": respectively.
• "unitCode" shall never be present, as JsonProperties are unitless.

5.2.6.5 Operational data types

5.2.6.5.1 Query

This datatype represents the information that is required in order to convey a query when a "Query Entities" operation or a "Query Temporal Evolution of Entities" operation is to be performed (as per clause 10.4.3 and clause 11.3.3, respectively).

The supported JSON members shall comply with the requirements provided in Table 5.2.6.5.1-1.

5.2.6.5.2 Subscription

This datatype represents a Context Subscription.

The supported JSON members shall comply with the requirements provided in Table 5.2.6.5.2-1.

At least one of (a) entities or (b) watchedAttributes shall be present, unless the member localOnly is set to true, in which case the execution of the request is limited to local scope (see clause 8.6).

The members (defined by Table 5.2.6.5.2-2) of the Subscription data structure are also defined. They are read-only and shall be automatically generated by NGSI-LD implementations. They shall not be provided by Context Subscribers. In the event that they are provided (in update or create operations) NGSI-LD implementations shall ignore them.

5.2.6.5.3 CSourceRegistration

This type represents the data needed to register a new Context Source.

The supported JSON members shall follow the indications provided in Table 5.2.6.5.3-1.

The members (defined by Table 5.2.6.5.3-2) of the CSourceRegistration data structure are also defined. They are read-only and shall be automatically generated by NGSI-LD implementations. In the event that they are provided (in update or create operations), NGSI-LD implementations shall ignore them.

5.2.6.5.4 Snapshot

This type represents the data needed to create and manage an NGSI-LD Snapshot.

The supported JSON members shall comply with the requirements provided in Table 5.2.6.5.4-1.

The following output only members (defined by Table 5.2.6.5.4-2) of the Snapshot data structure are also defined. They are read-only and shall be generated by NGSI-LD implementations. They shall not be provided by Context Consumers. In the event that they are provided (in update or create operations), NGSI-LD implementations shall ignore them.

5.2.6.5.5 EntityMap

This type represents the data needed to define an NGSI-LD Entity Map.

The supported JSON members shall comply with the requirements provided in Table 5.2.6.5.5-1.

The following output-only members (defined in Table 5.2.6.5.5-2) of the EntityMap data structure are also defined. They are read-only and shall be generated by NGSI-LD implementations. They shall not be provided by Context Consumers. In the event that they are provided in update operations, NGSI-LD implementations shall ignore them.

5.2.6.5.6 ContextSourceIdentity

This type represents the data uniquely identifying a Context Source, and if the Context Source supports multi-tenancy (see clause 7.8), uniquely identifying a Tenant within that Context Source.

The supported JSON members shall comply with the requirements provided in Table 5.2.6.5.6-1.

5.2.6.6 Structural data types

5.2.6.6.1 Endpoint

This datatype represents the parameters that are required in order to define an endpoint for notifications. This can include, in addition the endpoint's URI, a generic{key, value} array, named receiverInfo, which contains, in a generalized form, whatever extra information the Context Broker shall convey to the receiver in order for the Context Broker to successfully communicate with receiver (e.g. Authorization material), or for the receiver to correctly interpret the received content (e.g. the Link URL to fetch an @context). Additionally, it can include another generic{key, value} array, named notifierInfo, which contains the configuration that the Context Broker needs to know in order to correctly set up the communication channel towards the receiver (e.g. MQTT-Version, MQTT-QoS, in case of MQTT binding, as defined in ETSI TS 104 243 [24] clause 14.2).

The supported JSON members shall comply with the requirements provided in Table 5.2.6.6.1-1.

5.2.6.6.2 EntityInfo

This type represents what Entities, Entity Types or group of Entity IDs (as a regular expression pattern mandated by IEEE 1003.2™-1992 [13]) can be provided (by Context Sources).

The supported JSON members shall comply with the requirements provided in Table 5.2.6.6.2-1. id takes precedence over idPattern.

Notice that Cardinality of type being 1 implies that it is not possible to register what Entities can be provided by a Context Source just by their id or idPattern (i.e. without specifying their type).

5.2.6.6.3 EntitySelector

This type selects which entity or group of entities are queried or subscribed to by Context Consumers. Entities can be specified by their id, Entity Types or group of Entity IDs (as a regular expression pattern mandated by IEEE 1003.2™-1992 [13]).

The supported JSON members shall follow the indications provided in Table 5.2.6.6.3-1. id takes precedence over idPattern.

5.2.6.6.4 KeyValuePair

This datatype represents the optional information that is required when contacting an endpoint for notifications.

The supported members shall follow the indications provided in Table 5.2.6.6.4-1. They are intended to represent a key/value pair.

Example optional information includes additional HTTP Headers such as:

• The HTTP Authentication Header.
• The HTTP Prefer Header (IETF RFC 7240 [14]) used when notifying the GeoJSON Endpoint.

5.2.6.6.5 RegistrationInfo

The supported JSON members shall comply with the requirements provided in Table 5.2.6.6.5-1.

At least one element of RegistrationInfo shall be present.

5.2.6.6.6 RegistrationManagementInfo

This type represents the data to alter the default behaviour of a Context Broker when making a distributed operation request to a registered Context Source. The supported JSON members shall follow the indications provided in Table 5.2.6.6.6-1. Brokers may override these recommendations.

5.2.6.7 Parameter data types

5.2.6.7.1 TimeIntervalParams

The supported JSON members shall comply with the requirements provided in Table 5.2.6.7.1-1.

5.2.6.7.2 GeoParams

This datatype represents a geoquery used for Subscriptions.

The supported JSON members shall comply with the requirements provided in Table 5.2.6.7.2-1.

5.2.6.7.3 NotificationParams

This datatype represents the parameters that allow for conveying the details of a notification.

The supported JSON members shall comply with the requirements provided in Table 5.2.6.7.3-1.

The following output only members (defined by Table 5.2.6.7.3-2) of the NotificationParams data structure are also defined. They are read-only and shall be automatically generated by NGSI-LD implementations. They shall not be provided by Context Subscribers. In the event that they are provided (in update or create operations), NGSI-LD implementations shall ignore them.

In query or retrieve operations involving Subscriptions, implementations shall generate them as part of their representation.

5.2.6.7.4 TemporalParams

This datatype represents a temporal query.

The supported JSON members shall comply with the requirements provided in Table 5.2.6.7.4-1.