Disclaimer

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

Reference

RGS/CIM-009v191

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

The present document can be downloaded from the@#! Hyperlink ETSI Search & Browse Standards@#!application.

The present document may be made available in electronic versions and/or in print. The content of any electronic and/or print versions of the present document shall not be modified without the prior written authorization of ETSI. In case of any existing or perceived difference in contents between such versions and/or in print, the prevailing version of an ETSI deliverable is the one made publicly available in PDF format onETSI deliverrepository.

Users should be aware that the present document may be revised or have its status changed, this information is available in the@#! Hyperlink Milestones listing@#!.

If you find errors in the present document, please send your comments tothe relevant service listed underCommittee Support Staff.

Notice of disclaimer & limitation of liability

The information provided in the present deliverable is directed solely to professionals who have the appropriate degree of experience to understand and interpret its content in accordance with generally accepted engineering or

other professional standard and applicable regulations.

No recommendation as to products and services or vendors is made or should be implied.

No representation or warranty is made that this deliverable is technically accurate or sufficient or conforms to any law and/or governmental rule and/or regulation and further, no representation or warranty is made of merchantability or fitness for any particular purpose or against infringement of intellectual property rights.

In no event shall ETSI be held liable for loss of profits or any other incidental or consequential damages.

Any software contained in this deliverable is provided “AS IS” with no warranties, express or implied, including but not limited to, the warranties of merchantability, fitness for a particular purpose and non-infringement of intellectual property rights and ETSI shall not be held liable in any event for any damages whatsoever (including, without limitation, damages for loss of profits, business interruption, loss of information, or any other pecuniary loss) arising out of or related to the use of or inability to use the software.

Copyright Notification

No part may be reproduced or utilized in any form or by any means, electronic or mechanical, including photocopying and microfilm except as authorized by written permission of ETSI.The content of the PDF version shall not be modified without the written authorization of ETSI.The copyright and the foregoing restriction extend to reproduction in all media.

© ETSI 2025.

All rights reserved.

Intellectual Property Rights 19

Foreword 19

Modal verbs terminology 19

Executive summary 19

Introduction 20

1 Scope 21

2 References 21

2.1 Normative references 21

2.2 Informative references 22

3 Definition of terms, symbols and abbreviations 23

3.1 Terms 23

3.2 Symbols 26

3.3 Abbreviations 26

4 Context Information Management Framework 28

4.1 Introduction 28

4.2 NGSI-LD Information Model 28

4.2.1 Introduction 28

4.2.2 NGSI-LD Meta Model 29

4.2.3 Cross Domain Ontology 30

4.2.4 NGSI-LD domain-specific models and instantiation 31

4.2.5 UML representation 31

4.3 NGSI-LD Architectural Considerations 32

4.3.1 Introduction 32

4.3.2 Centralized architecture 33

4.3.3 Distributed architecture 33

4.3.4 Federated architecture 34

4.3.5 NGSI-LD API Structure and Implementation Options 35

4.3.6 Distributed Operations 40

4.3.6.1 Introduction 40

4.3.6.2 Additive Registrations 41

4.3.6.3 Proxied Registrations 41

4.3.6.4 Limiting Cascading Distributed Operations 42

4.3.6.5 Extra information to provide when contacting Context Source 42

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

4.3.6.7 Querying and Retrieving Distributed Entities as Unitary Operations 43

4.3.6.8 Backwards compatibility of Context Source payloads 44

4.3.7 Snapshots 46

4.4 Core and user NGSI-LD @context 46

4.5 NGSI-LD Data Representation 47

4.5.0 Introduction 47

4.5.1 NGSI-LD Entity Representation 47

4.5.2 NGSI-LD Property Representations 48

4.5.2.1 Introduction 48

4.5.2.2 Normalized NGSI-LD Property 48

4.5.2.3 Concise NGSI-LD Property 50

4.5.3 NGSI-LD Relationship Representations 51

4.5.3.1 Introduction 51

4.5.3.2 Normalized NGSI-LD Relationship 52

4.5.3.3 Concise NGSI-LD Relationship 53

4.5.4 Simplified Representation 54

4.5.5 Multi-Attribute Support 60

4.5.5.1 Introduction 60

4.5.5.2 Processing of Conflicting Transient Entities 60

4.5.5.3 Processing of Conflicting Attributes 60

4.5.6 Temporal Representation of an Entity 61

4.5.7 Temporal Representation of a Property 61

4.5.8 Temporal Representation of a Relationship 61

4.5.9 Simplified temporal representation of an Entity 61

4.5.10 Entity Type List Representation 65

4.5.11 Detailed Entity Type List Representation 65

4.5.12 Entity Type Information Representation 66

4.5.13 Attribute List Representation 66

4.5.14 Detailed Attribute List Representation 66

4.5.15 Attribute Information Representation 67

4.5.16 GeoJSON Representation of Entities 67

4.5.16.0 Foreword 67

4.5.16.1 Top-level “geometry” field selection algorithm 67

4.5.16.2 GeoJSON Representation of an individual Entity 67

4.5.16.3 GeoJSON Representation of Multiple Entities 68

4.5.17 Simplified GeoJSON Representation of Entities 68

4.5.17.0 Foreword 68

4.5.17.1 Simplified GeoJSON Representation of an individual Entity 68

4.5.17.2 Simplified GeoJSON Representation of multiple Entities 69

4.5.18 NGSI-LD LanguageProperty Representations 69

4.5.18.1 Introduction 69

4.5.18.2 Normalized NGSI-LD LanguageProperty 70

4.5.18.3 Concise NGSI-LD LanguageProperty 70

4.5.19 Aggregated temporal representation of an Entity 71

4.5.19.0 Foreword 71

4.5.19.1 Supported behaviours for aggregation functions 72

4.5.20 NGSI-LD VocabProperty Representations 73

4.5.20.1 Introduction 73

4.5.20.2 Normalized NGSI-LD VocabProperty 74

4.5.20.3 Concise NGSI-LD VocabProperty 74

4.5.21 NGSI-LD ListProperty Representations 75

4.5.21.1 Introduction 75

4.5.21.2 Normalized NGSI-LD ListProperty 75

4.5.21.3 Concise NGSI-LD ListProperty 75

4.5.22 NGSI-LD ListRelationship Representations 76

4.5.22.1 Introduction 76

4.5.22.2 Normalized NGSI-LD ListRelationship 76

4.5.22.3 Concise NGSI-LD ListRelationship 77

4.5.23 NGSI-LD Linked Entity Retrieval 77

4.5.23.1 Introduction 77

4.5.23.2 Inline Linked Entity Representation 78

4.5.23.3 Flattened Linked Entity Representation 78

4.5.24 NGSI-LD JsonProperty Representations 78

4.5.24.1 Introduction 78

4.5.24.2 Normalized NGSI-LD JsonProperty 78

4.5.24.3 Concise NGSI-LD JsonProperty 79

4.5.25 NGSI-LD EntityMap Representation 79

4.6 Data Representation Restrictions 80

4.6.1 Supported text encodings 80

4.6.2 Supported names 80

4.6.3 Supported data types for Values 80

4.6.4 Supported Content 81

4.6.5 Supported data types for LanguageMaps 82

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

4.7 Geospatial Properties 82

4.7.1 GeoJSON Geometries 82

4.7.2 Representation of GeoJSON Geometries in JSON-LD 83

4.7.3 Concise NGSI-LD GeoProperty 83

4.8 Temporal Properties 83

4.9 NGSI-LD Query Language 84

4.10 NGSI-LD Geoquery Language 92

4.11 NGSI-LD Temporal Query Language 94

4.12 NGSI-LD Pagination 95

4.13 Counting the Number of Results 96

4.14 Supporting Multiple Tenants 96

4.15 NGSI-LD Language Filter 96

4.16 Supporting Multiple Entity Types 97

4.17 NGSI-LD Entity Type Selection Language 97

4.18 NGSI-LD Scopes 98

4.19 NGSI-LD Scope Query Language 98

4.20 NGSI-LD Distributed Operation names 99

4.21 NGSI-LD Attribute Projection Language 101

4.22 Transient Storage of Entities and Attributes 102

4.23 Entity Ordering 102

4.23.1 Introduction 102

4.23.2 Datatype Comparison Order 102

4.23.3 NGSI-LD Entity Ordering Language 103

5 API Operation Definition 104

5.1 Introduction 104

5.2 Data Types 104

5.2.1 Introduction 104

5.2.2 Common members 104

5.2.3 @context 105

5.2.4 Entity 105

5.2.5 Property 106

5.2.6 Relationship 108

5.2.7 GeoProperty 110

5.2.8 EntityInfo 111

5.2.9 CSourceRegistration 111

5.2.10 RegistrationInfo 115

5.2.11 TimeInterval 115

5.2.12 Subscription 116

5.2.13 GeoQuery 118

5.2.14 NotificationParams 119

5.2.14.1 NotificationParams data type definition 119

5.2.14.2 Output only members 120

5.2.15 Endpoint 121

5.2.16 BatchOperationResult 121

5.2.17 BatchEntityError 122

5.2.18 UpdateResult 122

5.2.19 NotUpdatedDetails 122

5.2.20 EntityTemporal 122

5.2.21 TemporalQuery 123

5.2.22 KeyValuePair 124

5.2.23 Query 124

5.2.24 EntityTypeList 126

5.2.25 EntityType 126

5.2.26 EntityTypeInfo 127

5.2.27 AttributeList 127

5.2.28 Attribute 127

5.2.29 Feature 128

5.2.30 FeatureCollection 128

5.2.31 FeatureProperties 129

5.2.32 LanguageProperty 129

5.2.33 EntitySelector 131

5.2.34 RegistrationManagementInfo 132

5.2.35 VocabProperty 132

5.2.36 ListProperty 134

5.2.37 ListRelationship 136

5.2.38 JsonProperty 138

5.2.39 EntityMap 140

5.2.40 Context Source Identity 141

5.2.41 Snapshot 141

5.2.42 ExecutionResultDetails 143

5.2.43 OrderingParams 144

5.2.44 AggregationParams 144

5.3 Notification data types 145

5.3.1 Notification 145

5.3.2 CSourceNotification 146

5.3.3 TriggerReasonEnumeration 146

5.3.4 SnapshotNotification 146

5.4 NGSI-LD Fragments 147

5.5 Common Behaviours 148

5.5.1 Introduction 148

5.5.2 Error types 148

5.5.3 Error response payload body 149

5.5.4 General NGSI-LD validation 149

5.5.5 Default @context assignment 150

5.5.6 Operation execution and generic error handling 150

5.5.7 Term to URI expansion or compaction 150

5.5.8 Partial Update Patch Behaviour 151

5.5.9 Pagination Behaviour 153

5.5.9.1 General Pagination Behaviour 153

5.5.9.2 Pagination option using limit and offset 154

5.5.9.3 Pagination with Entity maps 154

5.5.10 Multi-Tenant Behaviour 154

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

5.5.11.0 Foreword 155

5.5.11.1 Batch Entity Creation case 155

5.5.11.2 Batch Entity Creation or Update (Upsert) case 155

5.5.11.3 Batch Entity Update case 155

5.5.11.4 Batch Entity Delete case 155

5.5.11.5 Batch Entity Merge case 156

5.5.12 Merge Patch Behaviour 156

5.5.13 Limiting operations to local scope 157

5.5.14 Distributed Transactional Behaviour 158

5.5.15 Snapshot Behaviour 158

5.6 Context Information Provision 159

5.6.1 Create Entity 159

5.6.1.1 Description 159

5.6.1.2 Use case diagram 159

5.6.1.3 Input data 159

5.6.1.4 Behaviour 159

5.6.1.5 Output data 160

5.6.2 Update Attributes 160

5.6.2.1 Description 160

5.6.2.2 Use case diagram 160

5.6.2.3 Input data 161

5.6.2.4 Behaviour 161

5.6.2.5 Output data 162

5.6.3 Append Attributes 162

5.6.3.1 Description 162

5.6.3.2 Use case diagram 162

5.6.3.3 Input data 163

5.6.3.4 Behaviour 163

5.6.3.5 Output data 164

5.6.4 Partial Attribute update 164

5.6.4.1 Description 164

5.6.4.2 Use case diagram 164

5.6.4.3 Input data 164

5.6.4.4 Behaviour 165

5.6.4.5 Output data 165

5.6.5 Delete Attribute 165

5.6.5.1 Description 165

5.6.5.2 Use case diagram 166

5.6.5.3 Input data 166

5.6.5.4 Behaviour 166

5.6.5.5 Output data 167

5.6.6 Delete Entity 167

5.6.6.1 Description 167

5.6.6.2 Use case diagram 167

5.6.6.3 Input data 168

5.6.6.4 Behaviour 168

5.6.6.5 Output data 168

5.6.7 Batch Entity Creation 168

5.6.7.1 Description 168

5.6.7.2 Use case diagram 168

5.6.7.3 Input data 169

5.6.7.4 Behaviour 169

5.6.7.5 Output data 170

5.6.8 Batch Entity Creation or Update (Upsert) 170

5.6.8.1 Description 170

5.6.8.2 Use case diagram 170

5.6.8.3 Input data 171

5.6.8.4 Behaviour 171

5.6.8.5 Output data 173

5.6.9 Batch Entity Update 173

5.6.9.1 Description 173

5.6.9.2 Use case diagram 173

5.6.9.3 Input data 173

5.6.9.4 Behaviour 174

5.6.9.5 Output data 175

5.6.10 Batch Entity Delete 175

5.6.10.1 Description 175

5.6.10.2 Use case diagram 175

5.6.10.3 Input data 175

5.6.10.4 Behaviour 176

5.6.10.5 Output data 177

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

5.6.11.1 Description 177

5.6.11.2 Use case diagram 177

5.6.11.3 Input data 177

5.6.11.4 Behaviour 177

5.6.11.5 Output data 178

5.6.12 Add Attributes to Temporal Evolution of an Entity 178

5.6.12.1 Description 178

5.6.12.2 Use case diagram 178

5.6.12.3 Input data 179

5.6.12.4 Behaviour 179

5.6.12.5 Output data 180

5.6.13 Delete Attribute from Temporal Evolution of an Entity 180

5.6.13.1 Description 180

5.6.13.2 Use case diagram 180

5.6.13.3 Input data 180

5.6.13.4 Behaviour 181

5.6.13.5 Output data 181

5.6.14 Modify Attribute instance in Temporal Evolution of an Entity 181

5.6.14.1 Description 181

5.6.14.2 Use case diagram 182

5.6.14.3 Input data 182

5.6.14.4 Behaviour 182

5.6.14.5 Output data 183

5.6.15 Delete Attribute instance from Temporal Evolution of an Entity 183

5.6.15.1 Description 183

5.6.15.2 Use case diagram 183

5.6.15.3 Input data 184

5.6.15.4 Behaviour 184

5.6.15.5 Output data 185

5.6.16 Delete Temporal Evolution of an Entity 185

5.6.16.1 Description 185

5.6.16.2 Use case diagram 185

5.6.16.3 Input data 185

5.6.16.4 Behaviour 185

5.6.16.5 Output data 186

5.6.17 Merge Entity 186

5.6.17.1 Description 186

5.6.17.2 Use case diagram 186

5.6.17.3 Input data 187

5.6.17.4 Behaviour 187

5.6.17.5 Output data 188

5.6.18 Replace Entity 188

5.6.18.1 Description 188

5.6.18.2 Use case diagram 188

5.6.18.3 Input data 189

5.6.18.4 Behaviour 189

5.6.18.5 Output data 190

5.6.19 Replace Attribute 190

5.6.19.1 Description 190

5.6.19.2 Use case diagram 190

5.6.19.3 Input data 190

5.6.19.4 Behaviour 190

5.6.19.5 Output data 191

5.6.20 Batch Entity Merge 191

5.6.20.1 Description 191

5.6.20.2 Use case diagram 191

5.6.20.3 Input data 192

5.6.20.4 Behaviour 192

5.6.20.5 Output data 193

5.6.21 Purge Entities 193

5.6.21.1 Description 193

5.6.21.2 Use case diagram 193

5.6.21.3 Input data 194

5.6.21.4 Behaviour 194

5.6.21.5 Output data 195

5.7 Context Information Consumption 196

5.7.1 Retrieve Entity 196

5.7.1.1 Description 196

5.7.1.2 Use case diagram 196

5.7.1.3 Input data 196

5.7.1.4 Behaviour 197

5.7.1.5 Output data 198

5.7.2 Query Entities 199

5.7.2.1 Description 199

5.7.2.2 Use case diagram 199

5.7.2.3 Input data 199

5.7.2.4 Behaviour 201

5.7.2.5 Output data 203

5.7.3 Retrieve Temporal Evolution of an Entity 204

5.7.3.1 Description 204

5.7.3.2 Use case diagram 204

5.7.3.3 Input data 204

5.7.3.4 Behaviour 205

5.7.3.5 Output data 206

5.7.4 Query Temporal Evolution of Entities 206

5.7.4.1 Description 206

5.7.4.2 Use case diagram 206

5.7.4.3 Input data 207

5.7.4.4 Behaviour 208

5.7.4.5 Output Data 211

5.7.5 Retrieve Available Entity Types 211

5.7.5.1 Description 211

5.7.5.2 Use case diagram 211

5.7.5.3 Input data 212

5.7.5.4 Behaviour 212

5.7.5.5 Output data 212

5.7.6 Retrieve Details of Available Entity Types 212

5.7.6.1 Description 212

5.7.6.2 Use case diagram 212

5.7.6.3 Input data 213

5.7.6.4 Behaviour 213

5.7.6.5 Output data 213

5.7.7 Retrieve Available Entity Type Information 213

5.7.7.1 Description 213

5.7.7.2 Use case diagram 213

5.7.7.3 Input data 214

5.7.7.4 Behaviour 214

5.7.7.5 Output data 214

5.7.8 Retrieve Available Attributes 214

5.7.8.1 Description 214

5.7.8.2 Use case diagram 214

5.7.8.3 Input data 215

5.7.8.4 Behaviour 215

5.7.8.5 Output data 215

5.7.9 Retrieve Details of Available Attributes 215

5.7.9.1 Description 215

5.7.9.2 Use case diagram 215

5.7.9.3 Input data 216

5.7.9.4 Behaviour 216

5.7.9.5 Output data 216

5.7.10 Retrieve Available Attribute Information 216

5.7.10.1 Description 216

5.7.10.2 Use case diagram 216

5.7.10.3 Input data 217

5.7.10.4 Behaviour 217

5.7.10.5 Output data 217

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

5.8 Context Information Subscription 218

5.8.1 Create Subscription 218

5.8.1.1 Description 218

5.8.1.2 Use case diagram 218

5.8.1.3 Input data 218

5.8.1.4 Behaviour 218

5.8.1.5 Output data 220

5.8.2 Update Subscription 220

5.8.2.1 Description 220

5.8.2.2 Use case diagram 220

5.8.2.3 Input data 220

5.8.2.4 Behaviour 221

5.8.2.5 Output data 221

5.8.3 Retrieve Subscription 221

5.8.3.1 Description 221

5.8.3.2 Use case diagram 221

5.8.3.3 Input data 222

5.8.3.4 Behaviour 222

5.8.3.5 Output data 222

5.8.4 Query Subscriptions 222

5.8.4.1 Description 222

5.8.4.2 Use case diagram 222

5.8.4.3 Input data 223

5.8.4.4 Behaviour 223

5.8.4.5 Output data 223

5.8.5 Delete Subscription 223

5.8.5.1 Description 223

5.8.5.2 Use case diagram 223

5.8.5.3 Input data 224

5.8.5.4 Behaviour 224

5.8.5.5 Output data 224

5.8.6 Notification behaviour 224

5.9 Context Source Registration 226

5.9.1 Introduction 226

5.9.2 Register Context Source 227

5.9.2.1 Description 227

5.9.2.2 Use case diagram 227

5.9.2.3 Input data 227

5.9.2.4 Behaviour 227

5.9.2.5 Output data 228

5.9.3 Update Context Source Registration 228

5.9.3.1 Description 228

5.9.3.2 Use case diagram 228

5.9.3.3 Input data 229

5.9.3.4 Behaviour 229

5.9.3.5 Output data 230

5.9.4 Delete Context Source Registration 230

5.9.4.1 Description 230

5.9.4.2 Use case diagram 230

5.9.4.3 Input data 230

5.9.4.4 Behaviour 230

5.9.4.5 Output data 231

5.10 Context Source Discovery 231

5.10.1 Retrieve Context Source Registration 231

5.10.1.1 Description 231

5.10.1.2 Use case diagram 231

5.10.1.3 Input data 231

5.10.1.4 Behaviour 231

5.10.1.5 Output data 232

5.10.2 Query Context Source Registrations 232

5.10.2.1 Description 232

5.10.2.2 Use case diagram 232

5.10.2.3 Input data 232

5.10.2.4 Behaviour 233

5.10.2.5 Output data 234

5.11 Context Source Registration Subscription 234

5.11.1 Introduction 234

5.11.2 Create Context Source Registration Subscription 234

5.11.2.1 Description 234

5.11.2.2 Use case diagram 234

5.11.2.3 Input data 235

5.11.2.4 Behaviour 235

5.11.2.5 Output data 236

5.11.3 Update Context Source Registration Subscription 236

5.11.3.1 Description 236

5.11.3.2 Use case diagram 236

5.11.3.3 Input data 237

5.11.3.4 Behaviour 237

5.11.3.5 Output data 237

5.11.4 Retrieve Context Source Registration Subscription 237

5.11.4.1 Description 237

5.11.4.2 Use case diagram 238

5.11.4.3 Input data 238

5.11.4.4 Behaviour 238

5.11.4.5 Output data 238

5.11.5 Query Context Source Registration Subscriptions 238

5.11.5.1 Description 238

5.11.5.2 Use case diagram 238

5.11.5.3 Input data 239

5.11.5.4 Behaviour 239

5.11.5.5 Output data 239

5.11.6 Delete Context Source Registration Subscription 239

5.11.6.1 Description 239

5.11.6.2 Use case diagram 239

5.11.6.3 Input data 240

5.11.6.4 Behaviour 240

5.11.6.5 Output data 240

5.11.7 Notification behaviour 240

5.12 Matching Context Source Registrations 241

5.13 Storing, Managing and Serving @contexts 242

5.13.1 Introduction 242

5.13.2 Add @context 243

5.13.2.1 Description 243

5.13.2.2 Use case diagram 243

5.13.2.3 Input data 244

5.13.2.4 Behaviour 244

5.13.2.5 Output data 244

5.13.3 List @contexts 244

5.13.3.1 Description 244

5.13.3.2 Use case diagram 244

5.13.3.3 Input data 245

5.13.3.4 Behaviour 245

5.13.3.5 Output data 245

5.13.4 Serve @context 246

5.13.4.1 Description 246

5.13.4.2 Use case diagram 246

5.13.4.3 Input data 246

5.13.4.4 Behaviour 246

5.13.4.5 Output data 247

5.13.5 Delete and Reload @context 247

5.13.5.1 Description 247

5.13.5.2 Use case diagram 247

5.13.5.3 Input data 247

5.13.5.4 Behaviour 247

5.13.5.5 Output data 248

5.14 Context Source Entity Mapping 248

5.14.1 Retrieve EntityMap 248

5.14.1.1 Description 248

5.14.1.2 Use case diagram 248

5.14.1.3 Input data 248

5.14.1.4 Behaviour 249

5.14.1.5 Output data 249

5.14.2 Update EntityMap 249

5.14.2.1 Description 249

5.14.2.2 Use case diagram 249

5.14.2.3 Input data 249

5.14.2.4 Behaviour 249

5.14.2.5 Output data 250

5.14.3 Delete EntityMap 250

5.14.3.1 Description 250

5.14.3.2 Use case diagram 250

5.14.3.3 Input data 250

5.14.3.4 Behaviour 250

5.14.3.5 Output data 250

5.14.4 Create EntityMap for Query Entities 251

5.14.4.1 Description 251

5.14.4.2 Use case diagram 251

5.14.4.3 Input data 251

5.14.4.4 Behaviour 252

5.14.4.5 Output data 254

5.14.5 Create EntityMap for Query Temporal Evolution of Entities 254

5.14.5.1 Description 254

5.14.5.2 Use case diagram 254

5.14.5.3 Input data 254

5.14.5.4 Behaviour 255

5.14.5.5 Output Data 257

5.15 Context Source Identity Information 257

5.15.1 Retrieve Context Source Identity Information 257

5.15.1.1 Description 257

5.15.1.2 Use case diagram 257

5.15.1.3 Input data 258

5.15.1.4 Behaviour 258

5.15.1.5 Output data 258

5.16 Snapshot Functionality 258

5.16.1 Create Snapshot 258

5.16.1.1 Description 258

5.16.1.2 Use case diagram 258

5.16.1.3 Input data 259

5.16.1.4 Behaviour 259

5.16.1.5 Output data 260

5.16.2 Clone Snapshot 260

5.16.2.1 Description 260

5.16.2.2 Use case diagram 260

5.16.2.3 Input data 260

5.16.2.4 Behaviour 260

5.16.2.5 Output data 261

5.16.3 Retrieve Snapshot Status 261

5.16.3.1 Description 261

5.16.3.2 Use case diagram 261

5.16.3.3 Input data 262

5.16.3.4 Behaviour 262

5.16.3.5 Output data 262

5.16.4 Update Snapshot Status 262

5.16.4.1 Description 262

5.16.4.2 Use case diagram 262

5.16.4.3 Input data 262

5.16.4.4 Behaviour 262

5.16.4.5 Output data 263

5.16.5 Delete Snapshot 263

5.16.5.1 Description 263

5.16.5.2 Use case diagram 263

5.16.5.3 Input data 263

5.16.5.4 Behaviour 263

5.16.5.5 Output data 264

5.16.6 Snapshot status notification behaviour 264

5.16.7 Purge Snapshots 264

5.16.7.1 Description 264

5.16.7.2 Use case diagram 264

5.16.7.3 Input data 264

5.16.7.4 Behaviour 265

5.16.7.5 Output data 265

6 API HTTP Binding 265

6.1 Introduction 265

6.2 Global Definitions and Resource Structure 265

6.3 Common Behaviours 269

6.3.1 Introduction 269

6.3.2 Error Types 269

6.3.3 Reporting errors 269

6.3.4 HTTP request preconditions 270

6.3.5 JSON-LD @context resolution 270

6.3.6 HTTP response common requirements 271

6.3.7 Representation of Entities 272

6.3.8 Notification behaviour 273

6.3.9 Csource Notification behaviour 274

6.3.10 Pagination behaviour 274

6.3.11 Including system Attributes 276

6.3.12 Simplified or aggregated temporal representation of Entities 276

6.3.13 Counting number of results 277

6.3.14 Tenant specification 277

6.3.15 GeoJSON representation of spatially bound entities 277

6.3.16 Expiration time for cached @contexts 277

6.3.17 Distributed Operations Caching and Timeout Behaviour 278

6.3.18 Limiting Distributed Operations 279

6.3.19 Extra information to provide when contacting Context Source 279

6.3.20 Invalid parameters 279

6.3.21 Optional profile information regarding versioning and datatype conformance 280

6.3.22 Snapshot specification 280

6.4 Resource: entities/ 280

6.4.1 Description 280

6.4.2 Resource definition 280

6.4.3 Resource methods 280

6.4.3.1 POST 280

6.4.3.2 GET 281

6.4.3.3 DELETE 285

6.5 Resource: entities/{entityId} 287

6.5.1 Description 287

6.5.2 Resource definition 288

6.5.3 Resource methods 288

6.5.3.1 GET 288

6.5.3.2 DELETE 290

6.5.3.3 PUT 291

6.5.3.4 PATCH 293

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

6.6.1 Description 294

6.6.2 Resource definition 294

6.6.3 Resource methods 295

6.6.3.1 POST 295

6.6.3.2 PATCH 296

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

6.7.1 Description 297

6.7.2 Resource definition 297

6.7.3 Resource methods 298

6.7.3.1 PATCH 298

6.7.3.2 DELETE 299

6.7.3.3 PUT 300

6.8 Resource: csourceRegistrations/ 302

6.8.1 Description 302

6.8.2 Resource definition 302

6.8.3 Resource methods 302

6.8.3.1 POST 302

6.8.3.2 GET 303

6.9 Resource: csourceRegistrations/{registrationId} 305

6.9.1 Description 305

6.9.2 Resource definition 305

6.9.3 Resource methods 306

6.9.3.1 GET 306

6.9.3.2 PATCH 306

6.9.3.3 DELETE 307

6.10 Resource: subscriptions/ 308

6.10.1 Description 308

6.10.2 Resource definition 308

6.10.3 Resource methods 308

6.10.3.1 POST 308

6.10.3.2 GET 309

6.11 Resource: subscriptions/{subscriptionId} 310

6.11.1 Description 310

6.11.2 Resource definition 310

6.11.3 Resource methods 310

6.11.3.1 GET 310

6.11.3.2 PATCH 311

6.11.3.3 DELETE 311

6.12 Resource: csourceSubscriptions/ 312

6.12.1 Description 312

6.12.2 Resource definition 312

6.12.3 Resource methods 312

6.12.3.1 POST 312

6.12.3.2 GET 313

6.13 Resource: csourceSubscriptions/{subscriptionId} 314

6.13.1 Description 314

6.13.2 Resource definition 314

6.13.3 Resource methods 314

6.13.3.1 GET 314

6.13.3.2 PATCH 315

6.13.3.3 DELETE 316

6.14 Resource: entityOperations/create 316

6.14.1 Description 316

6.14.2 Resource definition 317

6.14.3 Resource methods 317

6.14.3.1 POST 317

6.15 Resource: entityOperations/upsert 318

6.15.1 Description 318

6.15.2 Resource definition 318

6.15.3 Resource methods 319

6.15.3.1 POST 319

6.16 Resource: entityOperations/update 320

6.16.1 Description 320

6.16.2 Resource definition 321

6.16.3 Resource methods 321

6.16.3.1 POST 321

6.17 Resource: entityOperations/delete 322

6.17.1 Description 322

6.17.2 Resource definition 322

6.17.3 Resource methods 323

6.17.3.1 POST 323

6.18 Resource: temporal/entities/ 324

6.18.1 Description 324

6.18.2 Resource definition 324

6.18.3 Resource methods 325

6.18.3.1 POST 325

6.18.3.2 GET 325

6.19 Resource: temporal/entities/{entityId} 329

6.19.1 Description 329

6.19.2 Resource definition 329

6.19.3 Resource methods 329

6.19.3.1 GET 329

6.19.3.2 DELETE 331

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

6.20.1 Description 332

6.20.2 Resource definition 332

6.20.3 Resource methods 332

6.20.3.1 POST 332

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

6.21.1 Description 333

6.21.2 Resource definition 333

6.21.3 Resource methods 334

6.21.3.1 DELETE 334

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

6.22.1 Description 334

6.22.2 Resource definition 335

6.22.3 Resource methods 335

6.22.3.1 PATCH 335

6.22.3.2 DELETE 336

6.23 Resource: entityOperations/query 336

6.23.1 Description 336

6.23.2 Resource definition 336

6.23.3 Resource methods 337

6.23.3.1 POST 337

6.24 Resource: temporal/entityOperations/query 338

6.24.1 Description 338

6.24.2 Resource definition 338

6.24.3 Resource methods 339

6.24.3.1 POST 339

6.25 Resource: types/ 339

6.25.1 Description 339

6.25.2 Resource definition 340

6.25.3 Resource methods 340

6.25.3.1 GET 340

6.26 Resource: types/{type} 341

6.26.1 Description 341

6.26.2 Resource definition 341

6.26.3 Resource methods 341

6.26.3.1 GET 341

6.27 Resource: attributes/ 342

6.27.1 Description 342

6.27.2 Resource definition 342

6.27.3 Resource methods 342

6.27.3.1 GET 342

6.28 Resource: attributes/{attrId} 343

6.28.1 Description 343

6.28.2 Resource definition 343

6.28.3 Resource methods 343

6.28.3.1 GET 343

6.29 Resource: jsonldContexts/ 344

6.29.1 Description 344

6.29.2 Resource definition 344

6.29.3 Resource methods 344

6.29.3.1 POST 344

6.29.3.2 GET 345

6.30 Resource: jsonldContexts/{contextId} 346

6.30.1 Description 346

6.30.2 Resource definition 346

6.30.3 Resource methods 346

6.30.3.1 GET 346

6.30.3.2 DELETE 347

6.31 Resource: entityOperations/merge 348

6.31.1 Description 348

6.31.2 Resource definition 348

6.31.3 Resource methods 348

6.31.3.1 POST 348

6.32 Resource: entityMaps/{entityMapId} 350

6.32.1 Description 350

6.32.2 Resource definition 350

6.32.3 Resource methods 350

6.32.3.1 GET 350

6.32.3.2 PATCH 351

6.32.3.3 DELETE 351

6.33 Resource: info/sourceIdentity 352

6.33.1 Description 352

6.33.2 Resource definition 352

6.33.3 Resource methods 352

6.33.3.1 GET 352

6.34 Resource: entityMaps 353

6.34.1 Description 353

6.34.2 Resource definition 353

6.34.3 Resource methods 353

6.34.3.1 GET 353

6.34.3.2 POST 354

6.35 Resource: temporal/entityMaps 355

6.35.1 Description 355

6.35.2 Resource definition 355

6.35.3 Resource methods 355

6.35.3.1 GET 355

6.35.3.2 POST 356

6.36 Resource: snapshots 357

6.36.1 Description 357

6.36.2 Resource definition 357

6.36.3 Resource methods 357

6.36.3.1 POST 357

6.36.3.2 DELETE 358

6.37 Resource: snapshots/{snapshotId} 359

6.37.1 Description 359

6.37.2 Resource definition 359

6.37.3 Resource methods 359

6.37.3.1 GET 359

6.37.3.2 PATCH 360

6.37.3.3 DELETE 360

6.38 Resource: snapshots/{snapshotId}/clone 361

6.38.1 Description 361

6.38.2 Resource definition 361

6.38.3 Resource methods 361

6.38.3.1 POST 361

7 API MQTT Notification Binding 362

7.1 Introduction 362

7.2 Notification behaviour 362

Annex A (normative): NGSI-LD identifier considerations 364

A.1 Introduction 364

A.2 Entity identifiers 364

A.3 NGSI-LD namespace 364

Annex B (normative): Core NGSI-LD @context definition 365

Annex C (informative): Examples of using the API 371

C.1 Introduction 371

C.2 Entity Representation 371

C.2.1 Property Graph 371

C.2.2 Vehicle Entity 372

C.2.3 Parking Entity 385

C.2.4 @context 391

C.3 Context Source Registration 392

C.4 Context Subscription 392

C.5 HTTP REST API Examples 393

C.5.1 Introduction 393

C.5.2 Create Entity of Type Vehicle 393

C.5.2.1 HTTP Request 393

C.5.2.2 HTTP Response 393

C.5.3 Query Entities 393

C.5.3.1 Introduction 393

C.5.3.2 HTTP Request 394

C.5.3.3 HTTP Response 394

C.5.4 Query Entities (Pagination) 394

C.5.4.1 Introduction 394

C.5.4.2 HTTP Request 394

C.5.4.3 HTTP Response 394

C.5.5 Temporal Query 395

C.5.5.1 Introduction 395

C.5.5.2 HTTP Request #1 395

C.5.5.3 HTTP Response #1 395

C.5.5.4 HTTP Request #2 396

C.5.5.5 HTTP Response #2 396

C.5.6 Temporal Query (Simplified Representation) 396

C.5.6.1 Introduction 396

C.5.6.2 HTTP Request 396

C.5.6.3 HTTP Response 397

C.5.7 Retrieve Available Entity Types 397

C.5.7.1 Introduction 397

C.5.7.2 HTTP Request 397

C.5.7.3 HTTP Response 397

C.5.8 Retrieve Details of Available Entity Types 398

C.5.8.1 Introduction 398

C.5.8.2 HTTP Request 398

C.5.8.3 HTTP Response 398

C.5.9 Retrieve Available Entity Type Information 399

C.5.9.1 Introduction 399

C.5.9.2 HTTP Request 399

C.5.9.3 HTTP Response 399

C.5.10 Retrieve Available Attributes 400

C.5.10.1 Introduction 400

C.5.10.2 HTTP Request 400

C.5.10.3 HTTP Response 400

C.5.11 Retrieve Details of Available Attributes 400

C.5.11.1 Introduction 400

C.5.11.2 HTTP Request 400

C.5.11.3 HTTP Response 401

C.5.12 Retrieve Available Attribute Information 401

C.5.12.1 Introduction 401

C.5.12.2 HTTP Request 401

C.5.12.3 HTTP Response 402

C.5.13 Query Entities (Natural Language Filtering) 402

C.5.13.1 Introduction 402

C.5.13.2 HTTP Request 402

C.5.13.3 HTTP Response 402

C.5.14 Temporal Query (Aggregated Representation) 403

C.5.14.1 Introduction 403

C.5.14.2 HTTP Request 403

C.5.14.3 HTTP Response 403

C.5.15 Scope Queries 404

C.5.15.1 Introduction 404

C.5.15.2 HTTP Request 404

C.5.15.3 HTTP Response 404

C.5.16 Temporal Scope Queries 405

C.5.16.1 Introduction 405

C.5.16.2 HTTP Request 405

C.5.16.3 HTTP Response 405

C.6 Date Representation 407

C.7 @context utilization clarifications 408

C.8 Link header utilization clarifications 409

C.9 @context processing clarifications 411

C.10 ValueType datatype utilization clarifications 412

C.11 Entity with digital signature for a Property 412

Annex D (informative): Transformation Algorithms 414

D.1 Introduction 414

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

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

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

Annex E (informative): RDF-compatible specification of NGSI-LD meta-model 417

Annex F (informative): Conventions and syntax guidelines 418

Annex G (informative): Localization and Internationalization Support 419

G.0 Foreword 419

G.1 Introduction 419

G.1.0 Foreword 419

G.1.1 Associating an Entity with a Natural Language 419

G.1.2 Associating a Property with a Natural Language 419

G.1.3 Associating as equivalent entity 420

G.2 Natural Language Collation Support 420

G.2.0 Foreword 420

G.2.1 Maintain collations as metadata 421

G.2.2 Route language sensitive queries via a proxy 421

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

G.3.0 Foreword 421

G.3.1 Localizing Dates 421

Annex H (informative): Suggested actuation workflows 423

H.1 Actuators and feedback to the consumer 423

H.2 Architecture for actuation 423

H.3 Structure of Commands and additional Properties 424

H.3.0 Introduction 424

H.3.1 Property for listing available commands 425

H.3.2 Properties for command endpoints 425

H.4 Communication model 427

H.4.1 Possible communication models 427

H.4.2 Subscription/notification model 427

H.4.3 Forwarding model 428

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

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

Annex I (informative): Change history 433

History 436