ETSI GR CIM 008 V1.1.1 (2020-03)

Context Information Management (CIM); NGSI-LD Primer

DGR/CIM-008-NGSI-LD-Primer

General Information

• Status: Published
• Publication Date: 22-Mar-2020
• Technical Committee: CIM - cross-cutting Context Information Management
• Current Stage: 12 - Completion
• Due Date: 17-Jul-2020
• Completion Date: 23-Mar-2020

Standards Content (Sample)

ETSI GR CIM 008 V1.1.1 (2020-03)






GROUP REPORT
Context Information Management (CIM);
NGSI-LD Primer
Disclaimer
The present document has been produced and approved by the cross-cutting Context Information Management (CIM) ETSI
Industry Specification Group (ISG) and represents the views of those members who participated in this ISG.
It does not necessarily represent the views of the entire ETSI membership.

---------------------- Page: 1 ----------------------
2 ETSI GR CIM 008 V1.1.1 (2020-03)



Reference
DGR/CIM-008-NGSI-LD-Primer
Keywords
API, interoperability, IoT, smart city

ETSI
650 Route des Lucioles
F-06921 Sophia Antipolis Cedex - FRANCE

Tel.: [phone]  Fax: [phone]

Siret N° 348 623 562 00017 - NAF 742 C
Association à but non lucratif enregistrée à la
Sous-Préfecture de Grasse (06) N° 7803/88

Important notice
The present document can be downloaded from:
http://www.etsi.org/standards-search
The present document may be made available in electronic versions and/or in print. The content of any electronic and/or
print versions of the present document shall not be modified without the prior written authorization of ETSI. In case of any
existing or perceived difference in contents between such versions and/or in print, the prevailing version of an ETSI
deliverable is the one made publicly available in PDF format at www.etsi.org/deliver.
Users of the present document should be aware that the document may be subject to revision or change of status.
Information on the current status of this and other ETSI documents is available at
https://portal.etsi.org/TB/ETSIDeliverableStatus.aspx
If you find errors in the present document, please send your comment to one of the following services:
https://portal.etsi.org/People/CommiteeSupportStaff.aspx
Copyright Notification
No part may be reproduced or utilized in any form or by any means, electronic or mechanical, including photocopying
and microfilm except as authorized by written permission of ETSI.
The content of the PDF version shall not be modified without the written authorization of ETSI.
The copyright and the foregoing restriction extend to reproduction in all media.

© ETSI 2020.
All rights reserved.

DECT™, PLUGTESTS™, UMTS™ and the ETSI logo are trademarks of ETSI registered for the benefit of its Members.

3GPP™ and LTE™ 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.
ETSI

---------------------- Page: 2 ----------------------
3 ETSI GR CIM 008 V1.1.1 (2020-03)
Contents
Intellectual Property Rights . 4
Foreword . 4
Modal verbs terminology . 4
Executive summary . 4
Introduction . 4
1 Scope . 6
2 References . 6
2.1 Normative references . 6
2.2 Informative references . 6
3 Definition of terms, symbols and abbreviations . 6
3.1 Terms . 6
3.2 Symbols . 7
3.3 Abbreviations . 8
4 Motivation and an Example Use Case . 8
5 NGSI-LD Getting Started . 9
5.1 Introduction . 9
5.2 Architectural Assumptions . 9
5.3 Creating NGSI-LD Entities and Properties . 10
5.4 Retrieving NGSI-LD Entities and Properties . 11
5.5 Overview . 12
6 NGSI-LD Information Model . 12
7 NGSI-LD Information Representation . 15
8 NGSI-LD Information Provision . 15
8.1 Overview NGSI-LD Information Provision . 15
8.2 Creating/Deleting Entities . 16
8.2.1 Create Entity Using Link Header . 16
8.2.2 Delete Entity . 17
8.3 Creating/Updating/Deleting Properties and Relationships . 17
8.3.1 Appending an Entity Property/Relationship . 17
8.3.2 Updating an Entity Property/Relationship . 18
8.3.3 Partial Update of an Entity Property/Relationship . 18
8.3.4 Deleting an Entity Property/Relationship . 19
9 NGSI-LD Information Consumption . 19
9.1 Overview NGSI-LD Information Consumption . 19
9.2 Retrieving NGSI-LD Information . 20
9.2.1 Retrieving NGSI-LD Entity Using Simplified Representation . 20
9.3 NGSI-LD Query Language . 20
9.3.1 Querying NGSI-LD Entities by Type . 20
9.3.2 Querying NGSI-LD Entities by Type, Filtering by Property Value . 21
9.3.3 Querying NGSI-LD Entities by Type, Filtering by Relationship Object . 23
9.3.4 Querying NGSI-LD Entities by Type, Filtering by Meta Information . 24
9.4 Geographical NGSI-LD Queries . 24
10 NGSI-LD Information Subscriptions . 25
10.1 Overview NGSI-LD Information Subscriptions . 25
10.2 Creating Subscriptions . 25
10.2.1 Change-based Subscriptions, Updates and Resulting Notifications . 25
10.2.2 Time-based Subscriptions and Resulting Notifications . 28
Annex A: Change History . 30
History . 31

ETSI

---------------------- Page: 3 ----------------------
4 ETSI GR CIM 008 V1.1.1 (2020-03)
Intellectual Property Rights
Essential patents
IPRs essential or potentially essential to normative deliverables may have been declared to ETSI. The information
pertaining to these essential IPRs, if any, is 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 Web
server (https://ipr.etsi.org/).
Pursuant to the ETSI IPR Policy, no investigation, 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.
Trademarks
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.
Foreword
This Group Report (GR) has been produced by ETSI Industry Specification Group (ISG) cross-cutting Context
Information Management (CIM).
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 (this "Primer") is intended to give developers an introduction on how the NGSI-LD API is used.
The aim is to give developers, especially to those building applications and services on top of the NGSI-LD API, an
easy start by explaining the NGSI-LD API based on typical examples. For illustration purposes a scenario is introduced,
for which the information is modelled according to the NGSI-LD information model. Examples for providing
information, i.e. creating, updating and deleting information, and for requesting information, i.e. synchronous queries as
well as asynchronous subscribe/notify interactions, are given. The focus is on typical usage rather than on completeness
of all features.
Introduction
While ETSI GS CIM 009 [i.1] provides the complete specification of the NGSI-LD API, the present document, called
"Primer", is intended to give users an introduction to the use of the NGSI-LD API. The idea is to take a simple scenario,
i.e. a store that sells products to customers, for illustration purposes and show typical NGSI-LD API operation
examples. The examples for information provision show how entities, properties and relationships can be created,
updated, appended and deleted. The examples for information consumption show how entities can be synchronously
queried, filtered according to property values or filtered according to geographical location using geographic queries.
Finally change-based and time-based subscriptions are introduced and how these create asynchronous subscriptions
depending on a change-based or time-based trigger.
ETSI

---------------------- Page: 4 ----------------------
5 ETSI GR CIM 008 V1.1.1 (2020-03)
Most of the present document (NGSI-LD Primer) was created with the support of the following European Union
Horizon 2020 research projects: No. 732851 (FI-NEXT), No. 723156 (WISE-IoT), No. 732240 (SynchroniCity) and
No. 731993 (AutoPilot), No. 814918 (Fed4IoT), No. 779852 (IoTCrawler), No. 731884 (IoF2020).

ETSI

---------------------- Page: 5 ----------------------
6 ETSI GR CIM 008 V1.1.1 (2020-03)
1 Scope
The present document provides an introduction, in particular for developers, on how the NGSI-LD API, defined in
ETSI GS CIM 009 [i.1], is used. The focus is on typical use and is based on a small NGSI-LD information model
example. More information about the NGSI-LD information model can be found in ETSI GR CIM 002 [i.2].
2 References
2.1 Normative references
Normative references are not applicable in 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.
NOTE: While any hyperlinks included in this clause were valid at the time of publication, ETSI cannot guarantee
their long term validity.
The following referenced documents are not necessary for the application of the present document, but they assist the
user with regard to a particular subject area.
[i.1] ETSI GS CIM 009: "Context Information Management (CIM); NGSI-LD API".
[i.2] ETSI GR CIM 002: "Context Information Management (CIM); Use Cases (UC)".
[i.3] IETF RFC 3986: "Uniform Resource Identifier (URI): Generic Syntax".
NOTE: Available at https://tools.ietf.org/html/rfc3986.
[i.4] IEEE POSIX 1003.2™-1992: "IEEE Standard for Information Technology - Portable Operating
®
System Interfaces (POSIX ) - Part 2: Shell and Utilities".
[i.5] IETF RFC 7946: "The GeoJSON Format".
NOTE: Available at https://tools.ietf.org/html/rfc7946.
3 Definition of terms, symbols and abbreviations
3.1 Terms
For the purposes of the present document, the terms given in ETSI GS CIM 009 [i.1] and the following apply:
NOTE: The letters "NGSI-LD" were added to most terms to confirm that they are distinct from other terms of
similar/same name in use in other organizations, however, in the present document the letters "NGSI-LD"
are generally omitted for brevity.
NGSI-LD Attribute: reference to either the name of an NGSI-LD Property or to the name of an NGSI-LD
Relationship
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
ETSI

---------------------- Page: 6 ----------------------
7 ETSI GR CIM 008 V1.1.1 (2020-03)
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 Entity: informational representative of something that is supposed to exist in the real world, physically or
conceptually
NOTE: In the NGSI-LD API, any instance of such an entity is uniquely identified by a URI, and characterized
by reference to one or more NGSI-LD Entity Type(s). The API defined by the present document only
allows associating one NGSI-LD Entity Type per NGSI-LD Entity. This restriction will be removed in
future versions.
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
NOTE: In the NGSI-LD API, an NGSI-LD Entity Type is uniquely identified by a URI.
EXAMPLE 1: "Vehicle" is an NGSI-LD Entity Type and is identified with a proper URI.
EXAMPLE 2: Bob's private car whose plate number is "ABCD1234" is an NGSI-LD Entity whose NGSI-LD
Entity Type Name is "Vehicle".
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
linked NGSI-LD Entity) or an external resource (identified by a URI)
NGSI-LD Name: short-hand string (term) that locally identifies an NGSI-LD Entity Type, Property Type or
Relationship Type and which can be mapped to a URI which serves as a fully qualified identifier
EXAMPLE: The sentence "Bob's vehicle's speed is 40 km/h" can be represented by an NGSI-LD Property,
whose Name is "speed", and which characterizes an NGSI-LD Entity, which NGSI-LD Type
Name is "Vehicle". Such a name can be expanded to a fully qualified name in the form of a URI,
for instance "http://example.org/Vehicle" or "http://example.org/speed".
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 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, which is an NGSI-LD Entity, on the
other hand, and which uses the special hasObject property to define its target object
EXAMPLE: An NGSI-LD Entity of type (Type Name) "Vehicle" (when parked) can be the subject of an
NGSI-LD Relationship which object is an NGSI-LD Entity of type "Parking".
NGSI-LD Value: JSON value (i.e. a string, a number, true or false, an object, an array), or a 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 a JSON-LD structured value (i.e. a set, a list, a language-tagged string)
EXAMPLE: Bob's private car 'speed' NGSI-LD Value is the number 100 (kilometres per hour).
3.2 Symbols
Void.
ETSI

---------------------- Page: 7 ----------------------
8 ETSI GR CIM 008 V1.1.1 (2020-03)
3.3 Abbreviations
For the purposes of the present document, the abbreviations given in ETSI GS CIM 009 [i.1] and the following apply:
API Application Programming Interface
HTTP Hypertext Transfer Protocol
IETF Internet Engineering Task Force
IoT Internet of Things
IRI Internationalized Resource Identifier
ISG Industry Specification Group
JSON JavaScript Object Notation
JSON-LD JSON Linked Data
NGSI Next Generation Service Interfaces
NGSI-LD NGSI Linked Data
POSIX Portable Operating System Interface
RFC Request For Comments
URI Uniform Resource Identifier
URL Universal Resource Locator
4 Motivation and an Example Use Case
The concept of entity is at the core of the NGSI-LD model. Entities represent physical or conceptual objects existing in
the real world. Entities can have properties describing aspects of the object the entity stands for and relationships to
other entities. What kind of properties entities and relationships have is determined by the entity type?
As example use case, the present document is using a system for managing context information related to grocery stores
as depicted in Figure 4.1. It shows two instances of grocery store "6-Stars" and "Checker Market" with its location
depicted on a map, a product "Wine" and a customer "Paul".

Figure 4.1: Grocery store use case example
The entity types used in the example are Store, Customer, Shelf, Inventory item and Product. Figure 4.2 shows the
entity types together with the properties and relationships that instances of the respective entity type can have. As a
convention for this example, properties are defined as nouns, whereas relationships are defined as verbs. (The use of
this convention is not a requirement of NGSI-LD).
ETSI

---------------------- Page: 8 ----------------------
9 ETSI GR CIM 008 V1.1.1 (2020-03)

Figure 4.2: Entity types, relationships and properties of use case
5 NGSI-LD Getting Started
5.1 Introduction
The purpose of clause 5 is to give a first introduction to the NGSI-LD representation and API operations using the
HTTP binding. The examples can be used in an HTTP client (e.g. Postman or curl), targeting an NGSI-LD
implementation, i.e. an NGSI-LD Context Broker.
5.2 Architectural Assumptions
NGSI-LD defines an API together with an underlying information model. It does not define a specific system
architecture, but instead 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. For the following examples, the present document is using
the simplest architectural setup, i.e. a centralized NGSI-LD Context Broker that stores all information. The resulting
architecture is depicted in Figure 5.1 and requires a certain subset of NGSI-LD operations that are introduced in
clauses 5, 6, 7, 8, 9 and 10.
ETSI

---------------------- Page: 9 ----------------------
10 ETSI GR CIM 008 V1.1.1 (2020-03)

Figure 5.1: Basic architectural assumptions
The roles in this setup are Context Producers, Context Consumers and a Centralized Broker. The assumption is that the
Centralized Broker stores all information. Context Producers manage information, i.e. create, update and delete it,
whereas Context Consumers synchronously query information or subscribe to information to be asynchronously
notified. In the following, the assumption is that the Centralized Broker exposes the NGSI-LD API on
localhost:9090. Context Producers and Context Consumers are roles. The same software program can have both
roles at the same time, i.e. manage and request information.
It is planned to introduce more advanced architectural options in a future version of this Primer.
5.3 Creating NGSI-LD Entities and Properties
As entities are at the core of NGSI-LD, the following HTTP request creates a store entity with the id urn:ngsi-
ld:Store:001 of type Store (mapped to https://uri.etsi.org/ngsi-ld/primer/Store) in @context, the
properties address and storeName and the GeoProperty location (all mapped to the respective URI concepts in
@context).
POST /ngsi-ld/v1/entities/ HTTP/1.1
Host: localhost:9090
Content-Type: application/ld+json

{
  "@context": [
    {
      "Store": "https://uri.etsi.org/ngsi-ld/primer/Store",
      "address": "https://uri.etsi.org/ngsi-ld/primer/address",
      "storeName": "https://uri.etsi.org/ngsi-ld/primer/storeName",
      "streetAddress": "https://uri.etsi.org/ngsi-ld/primer/streetAddress",
      "addressRegion": "https://uri.etsi.org/ngsi-ld/primer/addressRegion",
      "addressLocality": "https://uri.etsi.org/ngsi-ld/primer/addressLocality",
      "postalCode": "https://uri.etsi.org/ngsi-ld/primer/postalCode"
    },
  "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context.jsonld"
  ],
  "id": "urn:ngsi-ld:Store:001",
  "type": "Store",
  "address": {
    "type": "Property",
    "value": {
      "streetAddress": "Main Street 65",
      "addressRegion": "Metropolis",
      "addressLocality": "Duckburg",
      "postalCode": "42000"
    }
  },
  "location": {
    "type": "GeoProperty",
    "value": {
  "type": "Point",
ETSI

---------------------- Page: 10 ----------------------
11 ETSI GR CIM 008 V1.1.1 (2020-03)
  "coordinates": [57.4874121, -20.2845607]
  }
  },
  "storeName": {
    "type": "Property",
    "value": "Checker Market"
  }
}

Figure 5.2: NGSI-LD entity creation
If the creation was successful, the response in Figure 5.3 with HTTP return code 201 Created is returned.
HTTP/1.1 201 Created
Date: Wed, 03 Apr 2019 15:08:33 GMT
location: /ngsi-ld/v1/entities/urn:ngsi-ld:Store:001

Figure 5.3: NGSI-LD entity creation result
NGSI-LD defines the three special properties location, observationSpace and operationSpace as
GeoProperty. A GeoProperty encodes a geographical location in GeoJSON format. A GeoProperty can be used for
the scope of geographic queries, whereby the API specification requires that such queries will only return results based
on that scope.
5.4 Retrieving NGSI-LD Entities and Properties
Now that the store entity with the id urn:ngsi-ld:Store:001 has been created, it can be retrieved. The request is
shown in Figure 5.4 and the successful result in Figure 5.5. Note that since no @context was provided in the request,
only the core context is returned, whereas all user-defined aspects are returned with fully qualified names. How to
provide the @context in requests without body is presented in clause 8.
GET /ngsi-ld/v1/entities/urn:ngsi-ld:Store:001 HTTP/1.1
Host: localhost:9090
Accept: application/ld+json

Figure 5.4: NGSI-LD entity retrieval
HTTP/1.1 200 OK
Date: Wed, 03 Apr 2019 15:50:09 GMTContent-Type: application/ld+json

{
 "id" : "urn:ngsi-ld:Store:001",
 "type" : "https://uri.etsi.org/ngsi-ld/primer/Store",
 "location" : {
  "type" : "GeoProperty",
  "value" : {
   "type" : "Point",
   "coordinates" : [ 57.4874121, -20.2845607 ]
  }
 },
 "https://uri.etsi.org/ngsi-ld/primer/address" : {
  "type" : "Property",
  "value" : {
   "https://uri.etsi.org/ngsi-ld/primer/addressLocality" : "Duck Village",
   "https://uri.etsi.org/ngsi-ld/primer/addressRegion" : "Metropolis",
   "https://uri.etsi.org/ngsi-ld/primer" : "42000",
   "https://uri.etsi.org/ngsi-ld/primer" : "Main Street 65"
  }
 },
 "https://uri.etsi.org/ngsi-ld/primer/storeName" : {
  "type" : "Property",
  "value" : "Checker Market"
 },
 "@context" : [ "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context.jsonld" ]
}

Figure 5.5: NGSI-LD entity retrieval result
ETSI

---------------------- Page: 11 ----------------------
12 ETSI GR CIM 008 V1.1.1 (2020-03)
5.5 Overview
Clause 6 explains the NGSI-LD Information Model in more detail and clause 7 focuses on the NGSI-LD representation
in JSON-LD and how it is used in the specified HTTP binding. Clause 8 gives typical examples of how NGSI-LD
information is managed, i.e. created, appended, updated and deleted. Clause 9 describes how to synchronously retrieve
and query NGSI-LD information and clause 10 gives examples for subscribing to NGSI-LD information and
asynchronously retrieve notifications.
Developers eager to experiment with NGSI-LD operations can also decide to immediately jump to clause 8 and
clause 9, and only go back to clause 6 and clause 7 in case there are open questions.
6 NGSI-LD Information Model
As already introduced, the core underlying concepts of the NGSI-LD Information Model, also referred to as the NGSI-
LD Meta-Model, are Entity, Relationship and Property. Logically, the types of entities, relationships and
properties are modelled as subclasses of the core concepts Entity, Relationship and Property respectively. For
our example use case, the types of entities, relationships and properties are shown in Figure 6.1. Note that the concepts
defined in the NGSI-LD specification are shown in bold. This includes the special property location, which is defined
as a GeoProperty in the specification.

Figure 6.1: Entities, properties and relationships of the use case
The subclass relationships can be explicitly modelled in an ontology, but for the purpose of using the NGSI-LD API,
they can also be implicitly assumed based on how they are used, i.e. as entity types or relationship and property names.
The important aspect for the use in the NGSI-LD API is that the respective concepts are explicitly defined as URIs in
the @context.
ETSI

-----------------
...