Disclaimer

Reference

RGS/CIM-009v171

Keywords

API, architecture, digital twins, GAP, information model, interoperability, NGSI-LD, smart agriculture, smart city, smart industry, smart manufacturing,smart water, WoT

ETSI

650 Route des Lucioles

F-06921 Sophia Antipolis Cedex - FRANCE

Tel.: +33 4 92 94 42 00 Fax: +33 4 93 65 47 16

Siret N° 348 623 562 00017 - APE 7112B

Association à but non lucratif enregistrée à la

Sous-Préfecture de Grasse (06) N° w061004871

Important notice

Notice of disclaimer & limitation of liability

Contents

Intellectual Property Rights 12

Foreword 12

Modal verbs terminology 12

Executive summary 12

Introduction 13

1 Scope 14

2 References 14

2.1 Normative references 14

2.2 Informative references 15

3 Definition of terms, symbols and abbreviations 16

3.1 Terms 16

3.2 Symbols 19

3.3 Abbreviations 19

4 Context Information Management Framework 20

4.1 Introduction 20

4.2 NGSI-LD Information Model 21

4.2.1 Introduction 21

4.2.2 NGSI-LD Meta Model 21

4.2.3 Cross Domain Ontology 23

4.2.4 NGSI-LD domain-specific models and instantiation 24

4.2.5 UML representation 24

4.3 NGSI-LD Architectural Considerations 25

4.3.1 Introduction 25

4.3.2 Centralized architecture 25

4.3.3 Distributed architecture 26

4.3.4 Federated architecture 27

4.3.5 NGSI-LD API Structure and Implementation Options 28

4.3.6 Distributed Operations 31

4.4 Core and user NGSI-LD @context 34

4.5 NGSI-LD Data Representation 35

4.5.0 Introduction 35

4.5.1 NGSI-LD Entity Representation 35

4.5.2 NGSI-LD Property Representations 36

4.5.3 NGSI-LD Relationship Representations 39

4.5.4 Simplified Representation 42

4.5.5 Multi-Attribute Support 46

4.5.6 Temporal Representation of an Entity 47

4.5.7 Temporal Representation of a Property 47

4.5.8 Temporal Representation of a Relationship 47

4.5.9 Simplified temporal representation of an Entity 48

4.5.10 Entity Type List Representation 51

4.5.11 Detailed Entity Type List Representation 51

4.5.12 Entity Type Information Representation 52

4.5.13 Attribute List Representation 52

4.5.14 Detailed Attribute List Representation 52

4.5.15 Attribute Information Representation 52

4.5.16 GeoJSON Representation of Entities 53

4.5.17 Simplified GeoJSON Representation of Entities 54

4.5.18 NGSI-LD LanguageProperty Representations 55

4.5.19 Aggregated temporal representation of an Entity 57

4.5.20 NGSI-LD VocabProperty Representations 59

4.5.21 NGSI-LD ListProperty Representations 60

4.5.22 NGSI-LD ListRelationship Representations 61

4.5.23 NGSI-LD Linked Entity Retrieval 63

4.5.24 NGSI-LD JsonProperty Representations 64

4.5.25 NGSI-LD EntityMap Representation 65

4.6 Data Representation Restrictions 65

4.6.1 Supported text encodings 65

4.6.2 Supported names 65

4.6.3 Supported data types for Values 66

4.6.4 Supported Content 67

4.6.5 Supported data types for LanguageMaps 67

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

4.7 Geospatial Properties 68

4.7.1 GeoJSON Geometries 68

4.7.2 Representation of GeoJSON Geometries in JSON-LD 68

4.7.3 Concise NGSI-LD GeoProperty 68

4.8 Temporal Properties 69

4.9 NGSI-LD Query Language 69

4.10 NGSI-LD Geoquery Language 77

4.11 NGSI-LD Temporal Query Language 79

4.12 NGSI-LD Pagination 80

4.13 Counting the Number of Results 80

4.14 Supporting Multiple Tenants 81

4.15 NGSI-LD Language Filter 81

4.16 Supporting Multiple Entity Types 82

4.17 NGSI-LD Entity Type Selection Language 82

4.18 NGSI-LD Scopes 82

4.19 NGSI-LD Scope Query Language 83

4.20 NGSI-LD Distributed Operation names 84

4.21 NGSI-LD Attribute Projection Language 85

5 API Operation Definition 86

5.1 Introduction 86

5.2 Data Types 86

5.2.1 Introduction 86

5.2.2 Common members 86

5.2.3 @context 87

5.2.4 Entity 87

5.2.5 Property 88

5.2.6 Relationship 90

5.2.7 GeoProperty 91

5.2.8 EntityInfo 92

5.2.9 CSourceRegistration 93

5.2.10 RegistrationInfo 96

5.2.11 TimeInterval 96

5.2.12 Subscription 97

5.2.13 GeoQuery 99

5.2.14 NotificationParams 99

5.2.15 Endpoint 101

5.2.16 BatchOperationResult 102

5.2.17 BatchEntityError 102

5.2.18 UpdateResult 103

5.2.19 NotUpdatedDetails 103

5.2.20 EntityTemporal 103

5.2.21 TemporalQuery 103

5.2.22 KeyValuePair 104

5.2.23 Query 104

5.2.24 EntityTypeList 106

5.2.25 EntityType 106

5.2.26 EntityTypeInfo 106

5.2.27 AttributeList 106

5.2.28 Attribute 107

5.2.29 Feature 107

5.2.30 FeatureCollection 108

5.2.31 FeatureProperties 108

5.2.32 LanguageProperty 108

5.2.33 EntitySelector 110

5.2.34 RegistrationManagementInfo 110

5.2.35 VocabProperty 112

5.2.36 ListProperty 114

5.2.37 ListRelationship 116

5.2.38 JsonProperty 118

5.2.39 EntityMap 119

5.2.40 Context Source Identity 121

5.3 Notification data types 121

5.3.1 Notification 121

5.3.2 CSourceNotification 122

5.3.3 TriggerReasonEnumeration 123

5.4 NGSI-LD Fragments 123

5.5 Common Behaviours 124

5.5.1 Introduction 124

5.5.2 Error types 124

5.5.3 Error response payload body 124

5.5.4 General NGSI-LD validation 125

5.5.5 Default @context assignment 125

5.5.6 Operation execution 125

5.5.7 Term to URI expansion or compaction 125

5.5.8 Partial Update Patch Behaviour 126

5.5.9 Pagination Behaviour 128

5.5.10 Multi-Tenant Behaviour 129

5.5.11 More than one instance of the same Entity in an Entity array 129

5.5.12 Merge Patch Behaviour 130

5.5.13 Limiting operations to local scope 132

5.5.14 Distributed Transactional Behaviour 132

5.6 Context Information Provision 133

5.6.1 Create Entity 133

5.6.2 Update Attributes 134

5.6.3 Append Attributes 136

5.6.4 Partial Attribute update 138

5.6.5 Delete Attribute 139

5.6.6 Delete Entity 141

5.6.7 Batch Entity Creation 142

5.6.8 Batch Entity Creation or Update (Upsert) 144

5.6.9 Batch Entity Update 147

5.6.10 Batch Entity Delete 149

5.6.11 Create or Update (Upsert) Temporal Evolution of an Entity 150

5.6.12 Add Attributes to Temporal Evolution of an Entity 152

5.6.13 Delete Attribute from Temporal Evolution of an Entity 153

5.6.14 Modify Attribute instance in Temporal Evolution of an Entity 155

5.6.15 Delete Attribute instance from Temporal Evolution of an Entity 157

5.6.16 Delete Temporal Evolution of an Entity 158

5.6.17 Merge Entity 160

5.6.18 Replace Entity 162

5.6.19 Replace Attribute 163

5.6.20 Batch Entity Merge 165

5.7 Context Information Consumption 167

5.7.1 Retrieve Entity 167

5.7.2 Query Entities 170

5.7.3 Retrieve Temporal Evolution of an Entity 174

5.7.4 Query Temporal Evolution of Entities 176

5.7.5 Retrieve Available Entity Types 179

5.7.6 Retrieve Details of Available Entity Types 180

5.7.7 Retrieve Available Entity Type Information 181

5.7.8 Retrieve Available Attributes 181

5.7.9 Retrieve Details of Available Attributes 182

5.7.10 Retrieve Available Attribute Information 183

5.7.11 Architecture-related aspects of retrieval of Entity Types and Attributes 184

5.8 Context Information Subscription 185

5.8.1 Create Subscription 185

5.8.2 Update Subscription 187

5.8.3 Retrieve Subscription 188

5.8.4 Query Subscriptions 189

5.8.5 Delete Subscription 190

5.8.6 Notification behaviour 191

5.9 Context Source Registration 193

5.9.1 Introduction 193

5.9.2 Register Context Source 193

5.9.3 Update Context Source Registration 195

5.9.4 Delete Context Source Registration 196

5.10 Context Source Discovery 197

5.10.1 Retrieve Context Source Registration 197

5.10.2 Query Context Source Registrations 198

5.11 Context Source Registration Subscription 201

5.11.1 Introduction 201

5.11.2 Create Context Source Registration Subscription 201

5.11.3 Update Context Source Registration Subscription 203

5.11.4 Retrieve Context Source Registration Subscription 204

5.11.5 Query Context Source Registration Subscriptions 204

5.11.6 Delete Context Source Registration Subscription 205

5.11.7 Notification behaviour 206

5.12 Matching Context Source Registrations 207

5.13 Storing, Managing and Serving @contexts 208

5.13.1 Introduction 208

5.13.2 Add @context 209

5.13.3 List @contexts 210

5.13.4 Serve @context 211

5.13.5 Delete and Reload @context 212

5.14 Context Source Entity Mapping 213

5.14.1 Retrieve EntityMap 213

5.14.2 Update EntityMap 214

5.14.3 Delete EntityMap 215

5.15 Context Source Identity Information 216

5.15.1 Retrieve Context Source Identity Information 216

6 API HTTP Binding 217

6.1 Introduction 217

6.2 Global Definitions and Resource Structure 217

6.3 Common Behaviours 221

6.3.1 Introduction 221

6.3.2 Error Types 221

6.3.3 Reporting errors 222

6.3.4 HTTP request preconditions 222

6.3.5 JSON-LD @context resolution 223

6.3.6 HTTP response common requirements 224

6.3.7 Representation of Entities 224

6.3.8 Notification behaviour 225

6.3.9 Csource Notification behaviour 226

6.3.10 Pagination behaviour 226

6.3.11 Including system generated Temporal Attributes 227

6.3.12 Simplified or aggregated temporal representation of Entities 228

6.3.13 Counting number of results 228

6.3.14 Tenant specification 229

6.3.15 GeoJSON representation of spatially bound entities 229

6.3.16 Expiration time for cached @contexts 229

6.3.17 Distributed Operations Caching and Timeout Behaviour 229

6.3.18 Limiting Distributed Operations 230

6.3.19 Extra information to provide when contacting Context Source 231

6.3.20 Invalid parameters 231

6.4 Resource: entities/ 231

6.4.1 Description 231

6.4.2 Resource definition 231

6.4.3 Resource methods 231

6.5 Resource: entities/{entityId} 236

6.5.1 Description 236

6.5.2 Resource definition 236

6.5.3 Resource methods 236

6.6 Resource: entities/{entityId}/attrs/ 242

6.6.1 Description 242

6.6.2 Resource definition 242

6.6.3 Resource methods 243

6.7 Resource: entities/{entityId}/attrs/{attrId} 245

6.7.1 Description 245

6.7.2 Resource definition 245

6.7.3 Resource methods 246

6.8 Resource: csourceRegistrations/ 249

6.8.1 Description 249

6.8.2 Resource definition 249

6.8.3 Resource methods 249

6.9 Resource: csourceRegistrations/{registrationId} 252

6.9.1 Description 252

6.9.2 Resource definition 252

6.9.3 Resource methods 253

6.10 Resource: subscriptions/ 255

6.10.1 Description 255

6.10.2 Resource definition 255

6.10.3 Resource methods 255

6.11 Resource: subscriptions/{subscriptionId} 257

6.11.1 Description 257

6.11.2 Resource definition 257

6.11.3 Resource methods 257

6.12 Resource: csourceSubscriptions/ 259

6.12.1 Description 259

6.12.2 Resource definition 259

6.12.3 Resource methods 259

6.13 Resource: csourceSubscriptions/{subscriptionId} 261

6.13.1 Description 261

6.13.2 Resource definition 261

6.13.3 Resource methods 261

6.14 Resource: entityOperations/create 263

6.14.1 Description 263

6.14.2 Resource definition 264

6.14.3 Resource methods 264

6.15 Resource: entityOperations/upsert 265

6.15.1 Description 265

6.15.2 Resource definition 265

6.15.3 Resource methods 266

6.16 Resource: entityOperations/update 267

6.16.1 Description 267

6.16.2 Resource definition 268

6.16.3 Resource methods 268

6.17 Resource: entityOperations/delete 269

6.17.1 Description 269

6.17.2 Resource definition 269

6.17.3 Resource methods 270

6.18 Resource: temporal/entities/ 271

6.18.1 Description 271

6.18.2 Resource definition 271

6.18.3 Resource methods 271

6.19 Resource: temporal/entities/{entityId} 274

6.19.1 Description 274

6.19.2 Resource definition 274

6.19.3 Resource methods 275

6.20 Resource: temporal/entities/{entityId}/attrs/ 277

6.20.1 Description 277

6.20.2 Resource definition 278

6.20.3 Resource methods 278

6.21 Resource: temporal/entities/{entityId}/attrs/{attrId} 279

6.21.1 Description 279

6.21.2 Resource definition 279

6.21.3 Resource methods 279

6.22 Resource: temporal/entities/{entityId}/attrs/{attrId}/ {instanceId} 280

6.22.1 Description 280

6.22.2 Resource definition 280

6.22.3 Resource methods 280

6.23 Resource: entityOperations/query 282

6.23.1 Description 282

6.23.2 Resource definition 282

6.23.3 Resource methods 282

6.24 Resource: temporal/entityOperations/query 283

6.24.1 Description 283

6.24.2 Resource definition 283

6.24.3 Resource methods 284

6.25 Resource: types/ 284

6.25.1 Description 284

6.25.2 Resource definition 284

6.25.3 Resource methods 284

6.26 Resource: types/{type} 285

6.26.1 Description 285

6.26.2 Resource definition 286

6.26.3 Resource methods 286

6.27 Resource: attributes/ 287

6.27.1 Description 287

6.27.2 Resource definition 287

6.27.3 Resource methods 287

6.28 Resource: attributes/{attrId} 288

6.28.1 Description 288

6.28.2 Resource definition 288

6.28.3 Resource methods 288

6.29 Resource: jsonldContexts/ 289

6.29.1 Description 289

6.29.2 Resource definition 289

6.29.3 Resource methods 289

6.30 Resource: jsonldContexts/{contextId} 291

6.30.1 Description 291

6.30.2 Resource definition 291

6.30.3 Resource methods 291

6.31 Resource: entityOperations/merge 293

6.31.1 Description 293

6.31.2 Resource definition 293

6.31.3 Resource methods 293

6.32 Resource: entityMaps/{entityMapId} 295

6.32.1 Description 295

6.32.2 Resource definition 295

6.32.3 Resource methods 295

6.33 Resource: info/sourceIdentity 297

6.33.1 Description 297

6.33.2 Resource definition 297

6.33.3 Resource methods 297

7 API MQTT Notification Binding 298

7.1 Introduction 298

7.2 Notification behaviour 298

A.1 Introduction 300

A.2 Entity identifiers 300

A.3 NGSI-LD namespace 300

C.1 Introduction 307

C.2 Entity Representation 307

C.2.1 Property Graph 307

C.2.2 Vehicle Entity 308

C.2.3 Parking Entity 321

C.2.4 @context 327

C.3 Context Source Registration 327

C.4 Context Subscription 328

C.5 HTTP REST API Examples 329

C.5.1 Introduction 329

C.5.2 Create Entity of Type Vehicle 329

C.5.2.1 HTTP Request 329

C.5.2.2 HTTP Response 329

C.5.3 Query Entities 329

C.5.3.1 Introduction 329

C.5.3.2 HTTP Request 329

C.5.3.3 HTTP Response 329

C.5.4 Query Entities (Pagination) 330

C.5.4.1 Introduction 330

C.5.4.2 HTTP Request 330

C.5.4.3 HTTP Response 330

C.5.5 Temporal Query 330

C.5.5.1 Introduction 330

C.5.5.2 HTTP Request #1 331

C.5.5.3 HTTP Response #1 331

C.5.5.2 HTTP Request #2 331

C.5.5.3 HTTP Response #2 331

C.5.6 Temporal Query (Simplified Representation) 332

C.5.6.1 Introduction 332

C.5.6.2 HTTP Request 332

C.5.6.3 HTTP Response 332

C.5.7 Retrieve Available Entity Types 333

C.5.7.1 Introduction 333

C.5.7.2 HTTP Request 333

C.5.7.3 HTTP Response 333

C.5.8 Retrieve Details of Available Entity Types 333

C.5.8.1 Introduction 333

C.5.8.2 HTTP Request 333

C.5.8.3 HTTP Response 334

C.5.9 Retrieve Available Entity Type Information 334

C.5.9.1 Introduction 334

C.5.9.2 HTTP Request 334

C.5.9.3 HTTP Response 335

C.5.10 Retrieve Available Attributes 335

C.5.10.1 Introduction 335

C.5.10.2 HTTP Request 335

C.5.10.3 HTTP Response 336

C.5.11 Retrieve Details of Available Attributes 336

C.5.11.1 Introduction 336

C.5.11.2 HTTP Request 336

C.5.11.3 HTTP Response 336

C.5.12 Retrieve Available Attribute Information 337

C.5.12.1 Introduction 337

C.5.12.2 HTTP Request 337

C.5.12.3 HTTP Response 337

C.5.13 Query Entities (Natural Language Filtering) 338

C.5.13.1 Introduction 338

C.5.13.2 HTTP Request 338

C.5.13.3 HTTP Response 338

C.5.14 Temporal Query (Aggregated Representation) 338

C.5.14.1 Introduction 338

C.5.14.2 HTTP Request 338

C.5.14.3 HTTP Response 338

C.5.15 Scope Queries 339

C.5.15.1 Introduction 339

C.5.15.2 HTTP Request 339

C.5.15.3 HTTP Response 339

C.5.16 Temporal Scope Queries 341

C.5.16.1 Introduction 341

C.5.16.2 HTTP Request 341

C.5.16.3 HTTP Response 341

C.6 Date Representation 342

C.7 @context utilization clarifications 343

C.8 Link header utilization clarifications 345

C.9 @context processing clarifications 346

D.1 Introduction 348

D.2 Algorithm for transforming an NGSI-LD Entity into a JSON-LD document (ALG1) 348

D.3 Algorithm for transforming an NGSI-LD Property into JSON-LD (ALG1.1) 349

D.4 Algorithm for transforming an NGSI-LD Relationship into JSON-LD (ALG1.2) 350

G.0 Foreword 353

G.1 Introduction 353

G.1.0 Foreword 353

G.1.1 Associating an Entity with a Natural Language 353

G.1.2 Associating a Property with a Natural Language 353

G.1.3 Associating as equivalent entity 354

G.2 Natural Language Collation Support 354

G.2.0 Foreword 354

G.2.1 Maintain collations as metadata 355

G.2.2 Route language sensitive queries via a proxy 355

G.3 Localization of Dates, Currency formats, etc. 355

G.3.0 Foreword 355

G.3.1 Localizing Dates 355

H.1 Actuators and feedback to the consumer 357

H.2 Architecture for actuation 357

H.3 Structure of Commands and additional Properties 358

H.3.0 Introduction 358

H.3.1 Property for listing available commands 359

H.3.2 Properties for command endpoints 359

H.4 Communication model 361

H.4.1 Possible communication models 361

H.4.2 Subscription/notification model 361

H.4.3 Forwarding model 362

H.5 Implementation of the subscription-based actuation workflow 363

H.6 Implementation of the registration-based actuation workflow 364

History 370

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 Web server (https://ipr.etsi.org/).

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

Foreword

This Group Specification (GS) has been produced by ETSI Industry Specification Group (ISG) cross-cutting Context Information Management (CIM).

Modal verbs terminology

In the present document "shall", "shall not", "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 Context Information Management API (NGSI-LD) Specification. The Context Information Management 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. This Context Information Management 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.17].

The ETSI ISG CIM has decided to give the name "NGSI-LD" to the Context Information Management API. The rationale is to reinforce the fact that the present document leverages on the former OMA NGSI 9 and 10 interfaces [i.3] and FIWARE® NGSIv2 [i.9] to incorporate the latest advances from Linked Data.

Most of the NGSI-LD API and the ETSI ISG CIM information model work referenced here 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), including many contributions from members of the FIWARE® Community.

1 Scope

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

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 at https://docbox.etsi.org/Reference/.

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 are not necessary for the application of the present document but they assist the user with regard to a particular subject area.

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 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 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 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 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 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 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. The target value contains data which is not available for interpretation.

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 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 Entities, 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 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 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 Context Information Management Framework

4.1 Introduction

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

4.2 NGSI-LD Information Model

4.2.1 Introduction

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

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

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

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.

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

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

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

4.2.3 Cross Domain Ontology

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

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

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

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

4.2.4 NGSI-LD domain-specific models and instantiation

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

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

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

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

4.2.5 UML representation

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

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

4.3 NGSI-LD Architectural Considerations

4.3.1 Introduction

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

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

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

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

4.3.2 Centralized architecture

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

4.3.3 Distributed architecture

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

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

4.3.4 Federated architecture

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

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

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

4.3.5 NGSI-LD API Structure and Implementation Options

As stated in clause 4.3.1, the NGSI-LD API is structured into a Core API and an optional Temporal API. In addition, the Registry API consists of the operations to be implemented by the Context Registry. Furthermore, the JSONLDContext API provides functionality for storing, managing, and serving JSON-LD @contexts. The APIs are structured according to their functionalities, which is also reflected in how the operations are structured in clause 5. Table 4.3.5‑1 introduces the API structure, the respective functionalities and lists the operations for each functionality, pointing to the clauses in which they are defined.

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

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

4.3.6 Distributed Operations

4.3.6.1 Introduction

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

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

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

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

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

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

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

4.3.6.2 Additive Registrations

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

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

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

4.3.6.3 Proxied Registrations

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

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

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

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

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

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

4.3.6.4 Limiting Cascading Distributed Operations

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

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

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

4.3.6.5 Extra information to provide when contacting Context Source

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

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

• If the key "jsonldContext" is defined, the value shall correspond to a URL reference as defined by the JSON-LD specification [2], section 3.1.
• The Context Broker shall apply a compaction operation as defined by the JSON-LD specification [2], section 4.1.5 over both payload and query parameters using the JSON-LD Context supplied in the value of the "jsonldContext" key-value pair, prior to distributing the request to the context source endpoint and forwarding with this JSON-LD context using an appropriate binding. Additionally, if a payload is defined in the initial request to the Context Broker, the "Content-Type" of the forwarded request shall be "application/json" and the Context Broker shall remove any @context members from the payload prior to distributing the request to the context source endpoint.
• If the key "accept" is defined, the value shall be a MIME type acceptable to the Context Broker (one of: "application/json", "application/ld+json").
• The response from the distributed endpoint shall be returned in this defined format and if necessary, the Context Broker shall be responsible for converting this to the desired content type when aggregating responses to the initial request.

4.3.6.7 Querying Distributed Entities as Unitary Operations

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

To support consistent pagination, and to process each Context Consumption request efficiently, it is necessary for the Context Broker to initially make a broad request to each registered Context Provider to return a list of available Entity ids matching the registration, before narrowing the result set using the query syntax. This Entity mapping is an internal operation, not usually exposed to the end user, however it is necessary to explicitly define a consistent mechanism for entity map creation, caching and retrieval.

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

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

4.4 Core and user NGSI-LD @context

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

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

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

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

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

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

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

• "@type": <Datatype's URI>.
• "@id": <Property's URI>.

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

• "@type": "@id".
• "@id": <Relationship's URI>.

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

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

4.5 NGSI-LD Data Representation

4.5.0 Introduction

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

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

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

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

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

4.5.1 NGSI-LD Entity Representation

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

The JSON-LD object contains the following members:

Mandatory

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

Optional

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

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

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

4.5.2 NGSI-LD Property Representations

4.5.2.1 Introduction

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

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

4.5.2.2 Normalized NGSI-LD Property

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

Mandatory

• "type": the fixed value "Property".
• "value": the Property Value (see definition of NGSI-LD Value in clause 3.1).
  An NGSI-LD Null (explained in clause 4.5.0 and defined in clause 3.1) can be used as the right-hand side of the "value" during partial update patch and merge patch (see clauses 5.5.8 and 5.5.12) to indicate a deletion of the Property, as well as in notifications and in temporal evolutions (for encoding a deleted Property).
  If the Value's datatype is a native JSON data type it shall be encoded directly as the member's value, else the member's value shall be a JSON object in the form:

• "@type": <Data Type URI>.
• "@value": Property Value.

Optional

• "datasetId": a URI as mandated by clause 4.5.5.
• "observedAt": a string as mandated by clause 4.8.
• "unitCode": a string representing the measurement unit corresponding to the Property value. It shall be encoded using the UNECE/CEFACT Common Codes for Units of Measurement [15].
• For each of the Properties this Property is associated with, a member whose key (a term) is the Property name and value is the result of serializing a Property (or any of its subclasses) in normalized representation (see clause 4.5.2.2).
• For each of the Relationships this Property is associated with, a member whose key (a term) is the Relationship name and value is the result of serializing a Relationship in normalized representation (see clause 4.5.3.2).

System Generated

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

Output Only

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

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

Prohibited

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

4.5.2.3 Concise NGSI-LD Property

An NGSI-LD Property without sub-attributes shall be represented in a concise but lossless representation by a member whose key is the Property name (a term) and whose value is the Property Value (see definition of NGSI-LD Value in clause 3.1). In this case the concise representation is equivalent to simplified representation (see clause 4.5.4).

Prohibited

• "type": shall never be present, as "Property" can be inferred. An exception to this inference rule occurs for geospatial Property Values, where the "GeoProperty" sub-type shall be inferred instead, if the Property Value resolves to a supported GeoJSON geometry (see clause 4.7).
• "value": shall never be present, as it can be inferred.

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

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

Mandatory

• "value": the Property Value (see definition of NGSI-LD Value in clause 3.1).
  An NGSI-LD Null (explained in clause 4.5.0 and defined in clause 3.1) can be used as the right-hand side of the "value" during partial update patch and merge patch (see clauses 5.5.8 and 5.5.12) to indicate a deletion of the Property, as well as in notifications and in temporal evolutions (for encoding a deleted Property).
  If the Value's datatype is a native JSON data type it shall be encoded directly as the member's value, else the member's value shall be a JSON object in the form:

• "@type": <Data Type URI>.
• "@value": Property Value.

Optional

• "datasetId": a URI as mandated by clause 4.5.5.
• "observedAt": a string as mandated by clause 4.8.
• "type": If missing, "Property" can be inferred by the presence of the "value" attribute. An exception to this inference rule occurs for geospatial Property Values, where the "GeoProperty" sub-type shall be inferred instead, if the Property Value resolves to a supported GeoJSON geometry (see clause 4.7).
• "unitCode": a string representing the measurement unit corresponding to the Property value. It shall be encoded using the UNECE/CEFACT Common Codes for Units of Measurement [15].
• For each of the Properties this Property is associated with, a member whose key (a term) is the Property name and value is the result of serializing a Property (or any of its subclasses) in concise representation (see clause 4.5.2.3).
• For each of the Relationships this Property is associated with, a member whose key (a term) is the Relationship name and value is the result of serializing a Relationship (or any of its subclasses) in concise representation (see clause 4.5.3.3).

System Generated

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

Output Only

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

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

Prohibited

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

4.5.3 NGSI-LD Relationship Representations

4.5.3.1 Introduction

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

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

4.5.3.2 Normalized NGSI-LD Relationship

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

Mandatory

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

Optional

• "datasetId": a URI as mandated by clause 4.5.5.
• "objectType": a string as mandated by clause 4.5.23
• "observedAt": a string as mandated by clause 4.8.
• For each Relationship this Relationship is associated with, a member whose key is the Relationship name (a term) and whose value is the result of serializing a Relationship (or any of its subclasses) as per the rules of representation of a Relationship in normalized representation. (see clause 4.5.3.2).
• For each Property this Relationship is associated with, a member whose key is the Property name (a term) and whose value is the result of serializing a Property (or any of its subclasses) as per the rules of representation of a Property in normalized representation. (see clause 4.5.2.2).

System Generated

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

Output Only

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

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

Prohibited

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

4.5.3.3 Concise NGSI-LD Relationship

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

Mandatory

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

Optional

• "datasetId": a URI as mandated by clause 4.5.5.
• "observedAt": a string as mandated by clause 4.8.
• "objectType": a string as mandated by clause 4.5.23.
• "type": If missing, "Relationship" can be inferred by the presence of the "object" attribute.
• For each Relationship this Relationship is associated with, a member whose key is the Relationship name (a term) and whose value is the result of serializing a Relationship (or any of its subclasses) as per the rules of representation of a Relationship in concise representation. (see clause 4.5.3.3).
• For each Property this Relationship is associated with, a member whose key is the Property name (a term) and whose value is the result of serializing a Property (or any of its subclasses) as per the rules of representation of a Property in concise representation. (see clause 4.5.2.3).

System Generated

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

Output Only

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

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

Prohibited

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

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

4.5.4 Simplified Representation

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

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

Mandatory

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

Optional

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

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

"name": {

  "dataset": {

    "@none": "David Robert Jones",

    "urn:ngsi-ld:datasetId:001": "David Bowie",

    "urn:ngsi-ld:datasetId:002": "Ziggy Stardust"

  }

}

• For each GeoProperty, a member whose key is the Property name (a term) and whose value is the Property Value.
  EXAMPLE 3: "location": {"type": "Point", "coordinates": [13.3986, 52.5547]}
• For each LanguageProperty, a member whose key is the Property name (a term) and whose value is a JSON Object containing a single Attribute with a key called "languageMap" where the value shall correspond to a LanguageProperty languageMap.
  EXAMPLE 4: "says": {"languageMap": {"en": "yes", "fr": "oui"}
• For each JsonProperty, a member whose key is the Property name (a term) and whose value is a JSON Object containing a single Attribute with a key called "json" where the value shall correspond to the raw JSON data that cannot be held in JSON-LD format. Within the example below, the id attribute is never expanded to @id and therefore does not have to be defined as a URI, and the value attribute is never expanded to ngsi-ld:hasValue.

EXAMPLE 5:

"parkingTickets": {

  "json": {

     "id": "85a6cc52-0589-45f9",

     "value": "Overstay 60 minutes"

  }

}

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

EXAMPLE 6: "gender": {"vocab": "Male"}

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

EXAMPLE 7: "providedBy": "urn:ngsi-ld:Device:31415"

EXAMPLE 8:

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

EXAMPLE 9:

EXAMPLE 10:

          "windSpeed": 60

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

EXAMPLE 11:

     {

     }

EXAMPLE 12:

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

EXAMPLE 13:

"providedBy": {

  "dataset": {

    "@none": "urn:ngsi-ld:Device:31415",

    "urn:ngsi-ld:datasetId:001": "urn:ngsi-ld:Device:27182",

    "urn:ngsi-ld:datasetId:002": "urn:ngsi-ld:Device:14142"

  }

}

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

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

EXAMPLE 15:

"periods": {

  "dataset": {

    "@none": ["First", "Second", "Third", "Fourth"],

    "urn:ngsi-ld:datasetId:001": ["1st", "2nd", "3rd", "4th"],

    "urn:ngsi-ld:datasetId:002": ["Primary", "Secondary", "Tertiary", "Quaternary"]

  }

}

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

"urn:ngsi-ld:BusStop:0101",

"urn:ngsi-ld:BusStop:0102",

"urn:ngsi-ld:BusStop:9912"

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

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

"route": [

         "urn:ngsi-ld:BusStop:0101", 

         "urn:ngsi-ld:BusStop:0102",

         "urn:ngsi-ld:BusStop:9912"

       "stopName": "High Street", 

       "location: {"type": "Point", "coordinates": [54.112,0.334]}}

       "stopName": "Station Road", 

       "location": {"type": "Point", "coordinates": [54.101,0.302]}}

       "id": "urn:ngsi-ld:BusStop:9912"

       "stopName": "Mornington Cresent", 

       "location: {"type": "Point", "coordinates": [54.142,0.332]}

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

EXAMPLE 19:

"route": {

  "dataset": {

    "@none": [

      "urn:ngsi-ld:BusStop:0101", 

      "urn:ngsi-ld:BusStop:0102", 

      "urn:ngsi-ld:BusStop:9912"

     ],

     "urn:ngsi-ld:datasetId:001": [

       "urn:ngsi-ld:BusStop:0101", 

       "urn:ngsi-ld:BusStop:0102",

       "urn:ngsi-ld:BusStop:0022"

     ],

     "urn:ngsi-ld:datasetId:002": [

       "urn:ngsi-ld:BusStop:0101", 

       "urn:ngsi-ld:BusStop:0102", 

       "urn:ngsi-ld:BusStop:0022", 

       "urn:ngsi-ld:BusStop:9912"

    ]

  }

}

4.5.5 Multi-Attribute Support

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

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

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

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

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

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

4.5.6 Temporal Representation of an Entity

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

4.5.7 Temporal Representation of a Property

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

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

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

4.5.8 Temporal Representation of a Relationship

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

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

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

4.5.9 Simplified temporal representation of an Entity

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

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

Mandatory

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

Optional

• "@context", a JSON-LD@context as described in clause 4.4.
• For each Property, a member whose key is the Property name (a term), the member value shall be a JSON-LD object labelled with the type "Property". Such JSON-LD object shall only contain a member whose key shall be "values". The value of the referred "values" member shall be a JSON-LD Array that shall contain as many array elements as Property instances (i.e. data points of the concerned Property) being represented. Each array element shall be another Array containing exactly two array elements: the first element shall be a Property value and the second element shall correspond to the associated Temporal Property (for instance observedAt).
  EXAMPLE 1:
  "name": {
    "type": "Property",
    "values": [
      [
        "Joe Bloggs",
        "2022-08-09T18:25:02Z"
      ],
      [
        "Bill Smith",
        "2022-08-10T18:25:02Z"
      ]
    ]
  }
• For each GeoProperty, a member whose key is the Property name (a term), the member value shall be a JSON-LD object labelled with the type "GeoProperty". Such JSON-LD object shall only contain a member whose key shall be "values". The value of the referred "values" member shall be a JSON-LD Array that shall contain as many array elements as GeoProperty instances (i.e. data points of the concerned GeoProperty) being represented. Each array element shall be another Array containing exactly two array elements: the first element shall be a GeoProperty value and the second element shall correspond to the associated Temporal Property (for instance observedAt).
• For each LanguageProperty, a member whose key is the Property name (a term), the member value shall be a JSON-LD object labelled with the type "LanguageProperty". Such JSON-LD object shall only contain a member whose key shall be "languageMaps". The value of the referred "languageMaps" member shall be a JSON-LD Array that shall contain as many array elements as LanguageProperty instances (i.e. data points of the concerned LanguageProperty) being represented. Each array element shall be another Array containing exactly two array elements: the first element shall be a JSON Object containing a single Attribute with a key called "languageMap" where the value shall correspond to a LanguageProperty languageMap and the second element shall correspond to the associated Temporal Property (for instance observedAt).
  EXAMPLE 2:

"says": {

  "type": "LanguageProperty",

  "languageMaps": [

    [

      {"languageMap": {"en": "yes", "fr": "oui"}},

      "2022-08-09T18:25:02Z"

    ],

    [

      {"languageMap": {"en": "no", "fr": "non"}},

      "2022-08-10T18:25:02Z"

    ]

  ]

}

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

"period": {

  "type": "ListProperty",

  "valueLists": [

    [

      ["First", "Second", "Third", "Fourth"],

      "2022-08-09T18:25:02Z"

    ],

    [

      ["1st", "2nd", "3rd", "4th"],

      "2022-08-10T18:25:02Z"

    ]

  ]

}

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

"parkingTickets": {

  "type": "JsonProperty",

  "jsons": [

    [

      {

        "json": [ 

          {

            "id": "85a6cc52-0589-45f9",

            "value": "Overstay 60 minutes"

          }

        ],

      },

      "2022-08-09T18:25:02Z"

    ],

    [

      {

        "json": [

          {

            "id": "85a6cc52-0589-45f9",

            "value": "Overstay 60 minutes"        

          },

          {

            "id": "x5c56s-0589-45f9",

            "value": "Overstay 45 minutes"

          }

        ]

      },

      "2022-08-10T18:25:02Z"

    ]

  ]

}

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

"gender": {

  "type": "VocabProperty",

  "vocabs": [

    [

      {"vocab": "Male"},

      "2022-08-09T18:25:02Z"

    ],

    [

      {"vocab": "Female"},

      "2022-08-10T18:25:02Z"

    ]

  ]

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

"spouse": {

  "type": "Relationship",

  "objects": [

    [

      "urn:ngsi-ld:Person:123455",

      "2022-08-09T18:25:02Z"

    ],

    [

      "urn:ngsi-ld:Person:999999",

      "2022-08-10T18:25:02Z"

    ]

  ]

}

"activeDevices": {

  "type": "Relationship",

  "objects": [

    [

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

      "2022-08-09T18:25:02Z"

    ],

    [

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

      "2022-08-10T18:25:02Z"

    ]

  ]

}

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

"membersPresent": {

  "type": "ListRelationship",

  "objectLists": [

    [

      ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"],

      "2022-08-09T18:25:02Z"

    ],

    [

      ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Eve", "urn:ngsi-ld:Person:Mallory"],

      "2022-08-10T18:25:02Z"

    ]

  ]

}

4.5.10 Entity Type List Representation

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

Mandatory

• "id" whose value shall be a URI that identifies the entity type list.
• "type": the fixed value "EntityTypeList".
• "typeList": JSON-LD array containing the entity type names.
  Optional
• "@context" a JSON-LD @context as described in clause 4.4.

4.5.11 Detailed Entity Type List Representation

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

Mandatory

• "attributeNames": JSON-LD array containing the names of attributes that instances of the entity type can have.
• "id" whose value shall be the URI that identifies the entity type.
• "type": the fixed value "EntityType".
• "typeName": name of entity type, short name if contained in @context.
  Optional
• "@context" a JSON-LD @context as described in clause 4.4.

4.5.12 Entity Type Information Representation

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

Mandatory

• "id" whose value shall be the URI that identifies the entity type.
• "type": the fixed value "EntityTypeInfo".
• "typeName": the URI that identifies the entity type (short name in case of availability in @context).
  Optional
• "@context" a JSON-LD @context as described in clause 4.4.

4.5.13 Attribute List Representation

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

Mandatory

• "attributeList": JSON-LD array containing the attribute names.
• "id": whose value shall be a URI that identifies the attribute list.
• "type": the fixed value "AttributeList".
  Optional
• "@context": a JSON-LD @context as described in clause 4.4.

4.5.14 Detailed Attribute List Representation

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

Mandatory

• "attributeName": the URI that identifies the attribute (short name in case of availability in @context).
• "id": whose value shall be the URI that identifies the attribute.
• "type": the fixed value "Attribute".
  Optional
• "@context": a JSON-LD @context as described in clause 4.4.
• "typeNames": an array of the names of entity types that have instances with attributes, which have the respective attribute name.

4.5.15 Attribute Information Representation

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

Mandatory

• "attributeName": the URI that identifies the attribute (short name in case of availability in @context).
• "id": whose value shall be the URI that identifies the attribute.
• "type": the fixed value "Attribute".
  Optional
• "@context": a JSON-LD @context as described in clause 4.4.
• "attributeCount": number of instances of this attribute.
• "attributeTypes": an array of attribute types (e.g. Property, Relationship, GeoProperty) for which instances with the attribute name exist.
• "typeNames": an array of the names of entity types that have instances with attributes, which have the respective attribute name.

4.5.16 GeoJSON Representation of Entities

4.5.16.0 Foreword

The NGSI-LD specification defines an alternative representation of Entities, to make NGSI-LD responses compatible with GIS (Geographic Information System) applications which support the GeoJSON format [8] and/or GeoJSON-LD [i.20].

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

4.5.16.1 Top-level "geometry" field selection algorithm

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

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

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

4.5.16.2 GeoJSON Representation of an individual Entity

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

Mandatory

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

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

• "type": the fixed value"Feature".
  Optional
• A JSON-LD @context as described in clause 4.4 if requested as part of the payload body.

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

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

4.5.16.3 GeoJSON Representation of Multiple Entities

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

Mandatory

• "type": the fixed value "FeatureCollection".
• "features": a JSON array of GeoJSON Feature objects as defined in clause 4.5.16.2. Note that separate @context elements for each Feature will not be present in the payload body
  Optional
• A JSON-LD @context as described in clause 4.4 if requested as part of the payload body.

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

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

4.5.17 Simplified GeoJSON Representation of Entities

4.5.17.0 Foreword

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

4.5.17.1 Simplified GeoJSON Representation of an individual Entity

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

Mandatory

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

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

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

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

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

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

4.5.17.2 Simplified GeoJSON Representation of multiple Entities

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

Mandatory

• "features": a JSON array of simplified GeoJSON Feature objects as defined in clause 4.5.17.1. Note that separate @context elements for each Feature will not be present in the payload body.
• "type": the fixed value "FeatureCollection".
  Optional
• A JSON-LD @context as described in clause 4.4 if requested as part of the payload body.

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

4.5.18 NGSI-LD LanguageProperty Representations

4.5.18.1 Introduction

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

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

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

4.5.18.2 Normalized NGSI-LD LanguageProperty

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

Mandatory

• "languageMap": a JSON object consisting of a set of a non-empty language tags as defined by IETF RFC 5646 [28] or the language tag "@none" which represents a default language, with each language tag mapping to a single string or array of strings. It represents a more specialized value.
  An NGSI-LD Null used during partial update patch and merge patch (see clauses 5.5.8 and 5.5.12) shall be encoded as the JSON object {"@none": "urn:ngsi-ld:null"}. The same representation is also used to indicate a deletion in notifications and in temporal evolutions for encoding a deleted LanguageProperty
• "type": the fixed value "LanguageProperty".
  Output Only
• "previousLanguageMap": only provided only in the case of notifications and only if the showChanges option is explicitly requested. It represents the previous LanguageProperty languageMap, before the triggering change. The representation is the same as that of "languageMap".

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

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

4.5.18.3 Concise NGSI-LD LanguageProperty

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

Mandatory

• "languageMap": a JSON object consisting of a set of a non-empty language tags as defined by IETF RFC 5646 [28] or the language tag "@none" which represents a default language, with each language tag mapping to a single string or array of strings. It represents a more specialized value.
  An NGSI-LD Null used during partial update patch and merge patch (see clauses 5.5.8 and 5.5.12) shall be encoded as the JSON object {"@none": "urn:ngsi-ld:null"}. The same representation is also used to indicate a deletion in notifications and the temporal evolutions for encoding a deleted LanguageProperty.
  Optional
• "type": If missing, "LanguageProperty" can be inferred by the presence of the "languageMap" attribute.
  Output Only
• "previousLanguageMap": only provided only in the case of notifications and only if the showChanges option is explicitly requested. It represents the previous LanguageProperty languageMap, before the triggering change. The representation is the same as that of "languageMap".

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

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

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

4.5.19 Aggregated temporal representation of an Entity

4.5.19.0 Foreword

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

The aggregation function is applied according to the following principles:

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

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

• A JSON-LD object containing the following members:

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

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

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

4.5.19.1 Supported behaviours for aggregation functions

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

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

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

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

The values supported by the aggrMethods parameter are the following:

• aggrMethods = "totalCount" / "distinctCount" / "sum" / "avg" / "min" / "max" / "stddev" / "sumsq"

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

4.5.20 NGSI-LD VocabProperty Representations

4.5.20.1 Introduction

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

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

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

4.5.20.2 Normalized NGSI-LD VocabProperty

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

Mandatory

• "type": the fixed value "VocabProperty".
• "vocab": a JSON object consisting of a single string or array of strings which can be type coerced into an IRI or array of IRIs. It represents a more specialized value.
  Output Only
• "previousVocab": only provided in case of notifications and only if the showChanges option is explicitly requested. It represents the previous VocabProperty vocab, before the triggering change. The representation is the same as that of "vocab".

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

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

4.5.20.3 Concise NGSI-LD VocabProperty

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

Mandatory

• "vocab": a JSON object consisting of a single string or array of strings which can be type coerced into an IRI or array of IRIs. It represents a more specialized value.
  Optional
• "type": If missing, "VocabProperty" can be inferred by the presence of the "vocab" attribute.
  Output Only
• "previousVocab": only provided only in the case of notifications and only if the showChanges option is explicitly requested. It represents the previous VocabProperty vocab, before the triggering change. The representation is the same as that of "vocab".

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

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

4.5.21 NGSI-LD ListProperty Representations

4.5.21.1 Introduction

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

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

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

4.5.21.2 Normalized NGSI-LD ListProperty

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

Mandatory

• "type": the fixed value "ListProperty".
• "valueList": a JSON representation ordered array of Property Values (see definition of NGSI-LD Value in clause 3.1). It represents a more specialized value.
  An array consisting of a single NGSI-LD Null (explained in 4.5.0 and defined in clause 3.1) can be used as the right-hand side of the "valueList" during partial update patch and merge patch (see clauses 5.5.8 and 5.5.12) to indicate a deletion of the ListProperty, as well as in notifications and in temporal evolutions (for encoding a deleted ListProperty).
  Output Only
• "previousValueList": only provided only in the case of notifications and only if the showChanges option is explicitly requested. It represents the previous ListProperty valueList, before the triggering change. The representation is the same as that of "valueList".

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

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

4.5.21.3 Concise NGSI-LD ListProperty

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

Mandatory

• "valueList": a JSON representation of a ordered array of Property Values (see definition of NGSI-LD Value in clause 3.1). It represents a more specialized value.
  An array consisting of a single NGSI-LD Null (explained in 4.5.0 and defined in clause 3.1) can be used as the right-hand side of the "valueList" during partial update patch and merge patch (see clauses 5.5.8 and 5.5.12) to indicate a deletion of the ListProperty, as well as in notifications and in temporal evolutions (for encoding a deleted ListProperty).
  Optional
• "type": If missing, "ListProperty" can be inferred by the presence of the "valueList" attribute.
  Output Only
• "previousValueList": only provided only in the case of notifications and only if the showChanges option is explicitly requested. It represents the previous ListProperty "valueList", before the triggering change. The representation is the same as that of "valueList".

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

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

4.5.22 NGSI-LD ListRelationship Representations

4.5.22.1 Introduction

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

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

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

4.5.22.2 Normalized NGSI-LD ListRelationship

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

Mandatory

• "objectList": a JSON representation of an ordered array of Relationship Objects each consisting of a JSON object containing a single Attribute with a key called "object" and its value holding the Relationship's object represented by a URI.
  An array consisting of a single NGSI-LD Null (explained in 4.5.0 and defined in clause 3.1) can be used as the right-hand side of the "objectList" during partial update patch and merge patch (see clauses 5.5.8 and 5.5.12) to indicate a deletion of the ListRelationship, as well as in notifications and in temporal evolutions (for encoding a deleted ListRelationship).
• "type": the fixed value "ListRelationship".
  Output Only
• "entityList": only provided in case of Linked Entity retrieval, and only if the inline join option is explicitly requested (see clause 4.5.23.2), where it is used to define the target Linked Entities of a ListRelationship's objectList in normalized representation.
• "previousObjectList": only provided in the case of notifications and only if the showChanges option is explicitly requested. It represents the previous ListRelationship objectList, before the triggering change. The representation is the same as that of "objectList".

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

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

4.5.22.3 Concise NGSI-LD ListRelationship

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

Mandatory

• "objectList": this represents a more specialized object and is represented by an ordered array of either:
  • a JSON objects containing a single Attribute with a key called "object" and its value holding the Relationship's object represented by a URI.
  • Strings representing URIs only, where expansion to Relationship objects can be inferred by the presence of the "objectList" attribute.
    An array consisting of a single NGSI-LD Null (explained in 4.5.0 and defined in clause 3.1) can be used as the right-hand side of the "objectList" during partial update patch and merge patch (see clauses 5.5.8 and 5.5.12) to indicate a deletion of the ListRelationship, as well as in notifications and in temporal evolutions (for encoding a deleted ListRelationship).
    Optional
• "type": If missing, "ListRelationship" can be inferred by the presence of the "objectList" attribute.
  Output Only
• "entityList": only provided if the inline join option is explicitly requested (see clause 4.5.23.2), where it is used to define the target Linked Entities of a ListRelationship's "objectList" in concise representation.
• "previousObjectList": only provided only in the case of notifications and only if the showChanges option is explicitly requested. It represents the previous ListRelationship objectList, before the triggering change. Optional. The representation is the same as that of "objectList".

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

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

4.5.23 NGSI-LD Linked Entity Retrieval

4.5.23.1 Introduction

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

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

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

4.5.23.2 Inline Linked Entity Representation

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

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

4.5.23.3 Flattened Linked Entity Representation

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

4.5.24 NGSI-LD JsonProperty Representations

4.5.24.1 Introduction

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

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

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

4.5.24.2 Normalized NGSI-LD JsonProperty

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

Mandatory

• "type": the fixed value "JsonProperty".
• "json": a raw JSON object (or array of objects) which contains data which is not available for JSON-LD interpretation. This means that the attributes within the JSON object are never subject to JSON-LD term expansion or compaction. It represents a more specialized value.
  Output Only
• "previousJson": only provided in case of notifications and only if the showChanges option is explicitly requested. It represents the previous JsonProperty json, before the triggering change. The representation is the same as that of "json".

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

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

4.5.24.3 Concise NGSI-LD JsonProperty

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

Mandatory

• "json": a raw JSON object which contains data which is not available for JSON-LD interpretation. This means that the attributes within the JSON object are never subject to JSON-LD term expansion or compaction. It represents a more specialized value.
  Optional
• "type": If missing, "JsonProperty" can be inferred by the presence of the "json" attribute.
  Output Only
• "previousJson": only provided in case of notifications and only if the showChanges option is explicitly requested. It represents the previous JsonProperty json, before the triggering change. The representation is the same as that of "json".

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

• "unitCode": shall never be present, as raw JSON objects are unitless.
• "value": shall never be present, as it is a generalization of vocab.

4.5.25 NGSI-LD EntityMap Representation

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

Mandatory

• "id": whose value shall be the URI that identifies the attribute.
• "type": the fixed value "EntityMap".
• "expiredBy": a DateTime string (as defined in clause 4.6.3) for encoding a timestamp indicating the time at which the EntityMap can no longer be used.
  Optional
• "@context": a JSON-LD @context as described in clause 4.4.
  Output Only
• "entityMap": a JSON-LD index map holding a unique list of entity ids (URIs) each of which lists the registrations that were fired by the previous request and successfully returned data.
• "linkedMaps": a JSON-LD index map holding a unique list of Context Source Registrations ids (URIs) each of which lists the entityMap used by a Context Source.

4.6 Data Representation Restrictions

4.6.1 Supported text encodings

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

4.6.2 Supported names

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

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

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

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

4.6.3 Supported data types for Values

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

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

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

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

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

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

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

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

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

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

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

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

4.6.4 Supported Content

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

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

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

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

4.6.5 Supported data types for LanguageMaps

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

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

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

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

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

4.7 Geospatial Properties

4.7.1 GeoJSON Geometries

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

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

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

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

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

4.7.2 Representation of GeoJSON Geometries in JSON-LD

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

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

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

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

4.7.3 Concise NGSI-LD GeoProperty

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

Mandatory

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

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

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

4.8 Temporal Properties

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

• observedAt is defined as the temporal Property at which a certain Property or Relationship became valid or was observed. For example, a temperature Value was measured by the sensor at this point in time.
• createdAt is defined as the temporal Property at which the Entity, Property or Relationship was entered into an NGSI-LD system.
• modifiedAt is defined as the temporal Property at which the Entity, Property or Relationship was last modified in an NGSI-LD system, e.g. in order to correct a previously entered incorrect value.
• deletedAt is defined as the temporal Property at which the Entity, Property or Relationship was deleted from an NGSI-LD system.

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

4.9 NGSI-LD Query Language

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

• filter out Entities by Attribute Values (target is the value member of a Property, see Table 5.2.5‑1, or the object member of a Relationship, see Table 5.2.6‑1);
• filter out Context Sources by the values of properties that describe them, defined when Context Sources are registered (target is the name of a Context Source Property member of the CSourceRegistration, see Table 5.2.9‑1).

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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