ETSI GS CIM 009 V1.7.1 (2023-06)

Context Information Management (CIM); NGSI-LD API

RGS/CIM-009v171

General Information

• Status: Not Published
• Technical Committee: CIM - cross-cutting Context Information Management
• Current Stage: 12 - Citation in the OJ (auto-insert)
• Due Date: 15-Jun-2023
• Completion Date: 06-Jun-2023

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.7.1 (2023-06)

Reference
RGS/CIM-009v171
Keywords
API, architecture, digital twins, GAP, information
model, interoperability, NGSI-LD, smart agriculture,
smart city, 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:
https://www.etsi.org/standards-search
The present document may be made available in electronic versions and/or in print. The content of any electronic and/or
print versions of the present document shall not be modified without the prior written authorization of ETSI. In case of any
existing or perceived difference in contents between such versions and/or in print, the prevailing version of an ETSI
deliverable is the one made publicly available in PDF format at www.etsi.org/deliver.
Users of the present document should be aware that the document may be subject to revision or change of status.
Information on the current status of this and other ETSI documents is available at
https://portal.etsi.org/TB/ETSIDeliverableStatus.aspx
If you find errors in the present document, please send your comment to one of the following services:
https://portal.etsi.org/People/CommiteeSupportStaff.aspx
If you find a security vulnerability in the present document, please report it through our
Coordinated Vulnerability Disclosure Program:
https://www.etsi.org/standards/coordinated-vulnerability-disclosure
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
rule and/or regulation and further, no representation or warranty is made of merchantability or fitness
and/or governmental
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 2023.
All rights reserved.
ETSI
3 ETSI GS CIM 009 V1.7.1 (2023-06)
Contents
Intellectual Property Rights . 17
Foreword . 17
Modal verbs terminology . 17
Executive summary . 17
Introduction . 18
1 Scope . 19
2 References . 19
2.1 Normative references . 19
2.2 Informative references . 20
3 Definition of terms, symbols and abbreviations . 21
3.1 Terms . 21
3.2 Symbols . 24
3.3 Abbreviations . 24
4 Context Information Management Framework . 25
4.1 Introduction . 25
4.2 NGSI-LD Information Model. 25
4.2.1 Introduction. 25
4.2.2 NGSI-LD Meta Model . 26
4.2.3 Cross Domain Ontology . 27
4.2.4 NGSI-LD domain-specific models and instantiation . 28
4.2.5 UML representation . 29
4.3 NGSI-LD Architectural Considerations . 29
4.3.1 Introduction. 29
4.3.2 Centralized architecture . 30
4.3.3 Distributed architecture . 30
4.3.4 Federated architecture . 31
4.3.5 NGSI-LD API Structure and Implementation Options . 32
4.3.6 Distributed Operations . 36
4.3.6.1 Introduction . 36
4.3.6.2 Additive Registrations . 36
4.3.6.3 Proxied Registrations . 37
4.3.6.4 Limiting Cascading Distributed Operations . 37
4.3.6.5 Extra information to provide when contacting Context Source . 37
4.3.6.6 Additional pre- and post-processing of extra information when contacting Context Source . 38
4.4 Core and user NGSI-LD @context . 38
4.5 NGSI-LD Data Representation. 39
4.5.0 Introduction. 39
4.5.1 NGSI-LD Entity Representation . 39
4.5.2 NGSI-LD Property Representations . 40
4.5.2.1 Introduction . 40
4.5.2.2 Normalized NGSI-LD Property . 40
4.5.2.3 Concise NGSI-LD Property . 41
4.5.3 NGSI-LD Relationship Representations . 42
4.5.3.1 Introduction . 42
4.5.3.2 Normalized NGSI-LD Relationship . 42
4.5.3.3 Concise NGSI-LD Relationship . 43
4.5.4 Simplified Representation . 44
4.5.5 Multi-Attribute Support . 45
4.5.6 Temporal Representation of an Entity . 46
4.5.7 Temporal Representation of a Property . 46
4.5.8 Temporal Representation of a Relationship . 46
4.5.9 Simplified Temporal Representation of an Entity . 46
4.5.10 Entity Type List Representation . 48
ETSI
4 ETSI GS CIM 009 V1.7.1 (2023-06)
4.5.11 Detailed Entity Type List Representation . 48
4.5.12 Entity Type Information Representation. 49
4.5.13 Attribute List Representation . 49
4.5.14 Detailed Attribute List Representation . 49
4.5.15 Attribute Information Representation . 49
4.5.16 GeoJSON Representation of Entities . 50
4.5.16.0 Foreword . 50
4.5.16.1 Top-level "geometry" field selection algorithm . 50
4.5.16.2 GeoJSON Representation of an individual Entity . 50
4.5.16.3 GeoJSON Representation of Multiple Entities . 51
4.5.17 Simplified GeoJSON Representation of Entities . 51
4.5.17.0 Foreword . 51
4.5.17.1 Simplified GeoJSON Representation of an individual Entity . 51
4.5.17.2 Simplified GeoJSON Representation of multiple Entities . 52
4.5.18 NGSI-LD LanguageProperty Representations . 52
4.5.18.1 Introduction . 52
4.5.18.2 Normalized NGSI-LD LanguageProperty . 52
4.5.18.3 Concise NGSI-LD LanguageProperty. 52
4.5.19 Aggregated Temporal Representation of an Entity . 53
4.5.19.0 Foreword . 53
4.5.19.1 Supported behaviours for aggregation functions . 54
4.5.20 NGSI-LD VocabularyProperty Representations . 56
4.5.20.1 Introduction . 56
4.5.20.2 Normalized NGSI-LD VocabularyProperty . 56
4.5.20.3 Concise NGSI-LD VocabularyProperty . 56
4.6 Data Representation Restrictions . 57
4.6.1 Supported text encodings . 57
4.6.2 Supported names . 57
4.6.3 Supported data types for Values . 57
4.6.4 Supported Entity Content . 58
4.6.5 Supported data types for LanguageMaps . 59
4.6.6 Ordering of Entities in arrays having more than one instance of the same Entity . 59
4.7 Geospatial Properties . 59
4.7.1 GeoJSON Geometries . 59
4.7.2 Representation of GeoJSON Geometries in JSON-LD . 59
4.7.3 Concise NGSI-LD GeoProperty . 60
4.8 Temporal Properties . 60
4.9 NGSI-LD Query Language . 61
4.10 NGSI-LD Geoquery Language . 67
4.11 NGSI-LD Temporal Query Language . 69
4.12 NGSI-LD Pagination . 70
4.13 Counting the Number of Results . 70
4.14 Supporting Multiple Tenants . 71
4.15 NGSI-LD Language Filter . 71
4.16 Supporting Multiple Entity Types . 72
4.17 NGSI-LD Entity Type Selection Language . 72
4.18 NGSI-LD Scopes . 73
4.19 NGSI-LD Scope Query Language . 73
4.20 NGSI-LD Distributed Operation Names . 74
5 API Operation Definition . 75
5.1 Introduction . 75
5.2 Data Types. 76
5.2.1 Introduction. 76
5.2.2 Common members . 76
5.2.3 @context . 76
5.2.4 Entity . 77
5.2.5 Property . 77
5.2.6 Relationship . 78
5.2.7 GeoProperty . 79
5.2.8 EntityInfo . 79
5.2.9 CSourceRegistration . 79
ETSI
5 ETSI GS CIM 009 V1.7.1 (2023-06)
5.2.10 RegistrationInfo . 83
5.2.11 TimeInterval . 83
5.2.12 Subscription . 83
5.2.13 GeoQuery . 85
5.2.14 NotificationParams . 85
5.2.14.1 NotificationParams data type definition . 85
5.2.14.2 Additional members . 86
5.2.15 Endpoint . 87
5.2.16 BatchOperationResult . 87
5.2.17 BatchEntityError . 88
5.2.18 UpdateResult. 88
5.2.19 NotUpdatedDetails. 88
5.2.20 EntityTemporal . 88
5.2.21 TemporalQuery . 89
5.2.22 KeyValuePair . 89
5.2.23 Query . 89
5.2.24 EntityTypeList . 90
5.2.25 EntityType . 90
5.2.26 EntityTypeInfo . 91
5.2.27 AttributeList . 91
5.2.28 Attribute . 91
5.2.29 Feature . 92
5.2.30 FeatureCollection . 92
5.2.31 FeatureProperties . 93
5.2.32 LanguageProperty . 93
5.2.33 EntitySelector . 94
5.2.34 RegistrationManagementInfo . 94
5.2.35 VocabularyProperty . 95
5.3 Notification data types . 95
5.3.1 Notification . 95
5.3.2 CSourceNotification . 96
5.3.3 TriggerReasonEnumeration . 97
5.4 NGSI-LD Fragments . 97
5.5 Common Behaviours . 98
5.5.1 Introduction. 98
5.5.2 Error types . 98
5.5.3 Error response payload body . 98
5.5.4 General NGSI-LD validation . 98
5.5.5 Default @context assignment . 99
5.5.6 Operation execution . 99
5.5.7 Term to URI expansion or compaction . 99
5.5.8 Partial Update Patch Behaviour . 100
5.5.9 Pagination Behaviour . 102
5.5.10 Multi-Tenant Behaviour . 103
5.5.11 More than one instance of the same Entity in an Entity array . 103
5.5.11.0 Foreword . 103
5.5.11.1 Batch Entity Creation case . 104
5.5.11.2 Batch Entity Creation or Update (Upsert) case . 104
5.5.11.3 Batch Entity Update case . 104
5.5.11.4 Batch Entity Delete case . 104
5.5.11.5 Batch Entity Merge case . 104
5.5.12 Merge Patch Behaviour . 104
5.6 Context Information Provision . 106
5.6.1 Create Entity . 106
5.6.1.1 Description . 106
5.6.1.2 Use case diagram . 106
5.6.1.3 Input data . 106
5.6.1.4 Behaviour . 106
5.6.1.5 Output data . 107
5.6.2 Update Attributes . 107
5.6.2.1 Description . 107
5.6.2.2 Use case diagram . 107
ETSI
6 ETSI GS CIM 009 V1.7.1 (2023-06)
5.6.2.3 Input data . 108
5.6.2.4 Behaviour . 108
5.6.2.5 Output data . 109
5.6.3 Append Attributes . 109
5.6.3.1 Description . 109
5.6.3.2 Use case diagram . 109
5.6.3.3 Input data . 110
5.6.3.4 Behaviour . 110
5.6.3.5 Output data . 111
5.6.4 Partial Attribute update . 111
5.6.4.1 Description . 111
5.6.4.2 Use case diagram . 111
5.6.4.3 Input data . 112
5.6.4.4 Behaviour . 112
5.6.4.5 Output data . 113
5.6.5 Delete Attribute . 113
5.6.5.1 Description . 113
5.6.5.2 Use case diagram . 113
5.6.5.3 Input data . 113
5.6.5.4 Behaviour . 114
5.6.5.5 Output data . 114
5.6.6 Delete Entity . 114
5.6.6.1 Description . 114
5.6.6.2 Use case diagram . 115
5.6.6.3 Input data . 115
5.6.6.4 Behaviour . 115
5.6.6.5 Output data . 116
5.6.7 Batch Entity Creation. 116
5.6.7.1 Description . 116
5.6.7.2 Use case diagram . 116
5.6.7.3 Input data . 116
5.6.7.4 Behaviour . 116
5.6.7.5 Output data . 117
5.6.8 Batch Entity Creation or Update (Upsert) . 117
5.6.8.1 Description . 117
5.6.8.2 Use case diagram . 117
5.6.8.3 Input data . 118
5.6.8.4 Behaviour . 118
5.6.8.5 Output data . 120
5.6.9 Batch Entity Update . 120
5.6.9.1 Description . 120
5.6.9.2 Use case diagram . 120
5.6.9.3 Input data . 120
5.6.9.4 Behaviour . 120
5.6.9.5 Output data . 122
5.6.10 Batch Entity Delete . 122
5.6.10.1 Description . 122
5.6.10.2 Use case diagram . 122
5.6.10.3 Input data . 122
5.6.10.4 Behaviour . 122
5.6.10.5 Output data . 123
5.6.11 Create or Update (Upsert) Temporal Representation of an Entity . 123
5.6.11.1 Description . 123
5.6.11.2 Use case diagram . 123
5.6.11.3 Input data . 124
5.6.11.4 Behaviour . 124
5.6.11.5 Output data . 125
5.6.12 Add Attributes to Temporal Representation of an Entity . 125
5.6.12.1 Description . 125
5.6.12.2 Use case diagram . 125
5.6.12.3 Input data . 125
5.6.12.4 Behaviour . 126
ETSI
7 ETSI GS CIM 009 V1.7.1 (2023-06)
5.6.12.5 Output data . 126
5.6.13 Delete Attribute from Temporal Representation of an Entity . 126
5.6.13.1 Description . 126
5.6.13.2 Use case diagram . 126
5.6.13.3 Input data . 127
5.6.13.4 Behaviour . 127
5.6.13.5 Output data . 128
5.6.14 Modify Attribute instance in Temporal Representation of an Entity . 128
5.6.14.1 Description . 128
5.6.14.2 Use case diagram . 128
5.6.14.3 Input data . 129
5.6.14.4 Behaviour . 129
5.6.14.5 Output data . 129
5.6.15 Delete Attribute instance from Temporal Representation of an Entity . 130
5.6.15.1 Description . 130
5.6.15.2 Use case diagram . 130
5.6.15.3
...