ETSI GS CIM 009 V1.9.1 (2025-07)

Context Information Management (CIM); NGSI-LD API

RGS/CIM-009v191

General Information

• Status: Not Published
• Technical Committee: CIM - cross-cutting Context Information Management
• Current Stage: 12 - Citation in the OJ (auto-insert)
• Due Date: 11-Jul-2025
• Completion Date: 02-Jul-2025

Standards Content (Sample)

GROUP SPECIFICATION
Context Information Management (CIM);
NGSI-LD API
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.

2 ETSI GS CIM 009 V1.9.1 (2025-07)

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.: [phone]  Fax: [phone]

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
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 on ETSI deliver repository.
Users should be aware that the present document may be revised or have its status changed,
this information is available in the Milestones listing.
If you find errors in the present document, please send your comments to
the relevant service listed under Committee Support Staff.
If you find a security vulnerability in the present document, please report it through our
Coordinated Vulnerability Disclosure (CVD) program.
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.
ETSI
3 ETSI GS CIM 009 V1.9.1 (2025-07)
Contents
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
ETSI
4 ETSI GS CIM 009 V1.9.1 (2025-07)
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
ETSI
5 ETSI GS CIM 009 V1.9.1 (2025-07)
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
ETSI
6 ETSI GS CIM 009 V1.9.1 (2025-07)
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
ETSI
7 ETSI GS CIM 009 V1.9.1 (2025-07)
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 .
...