1、 ETSI GS CIM 004 V1.1.1 (2018-04) Context Information Management (CIM); Application Programming Interface (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
2、 those members who participated in this ISG. It does not necessarily represent the views of the entire ETSI membership. GROUP SPECIFICATION ETSI ETSI GS CIM 004 V1.1.1 (2018-04)2 Reference DGS/CIM-004-APIprelim Keywords API, architecture, GAP, information model, interoperability, smart city ETSI 650
3、 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 - NAF 742 C Association but non lucratif enregistre la Sous-Prfecture de Grasse (06) N 7803/88 Important notice The present document can be downloaded from: http:/www.
4、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 differe
5、nce in contents between such versions and/or in print, the only prevailing document is the print of the Portable Document Format (PDF) version kept on a specific network drive within ETSI Secretariat. Users of the present document should be aware that the document may be subject to revision or chang
6、e 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/CommiteeSupportSta
7、ff.aspx Copyright Notification No part may be reproduced or utilized in any form or by any means, electronic or mechanical, including photocopying and microfilm except as authorized by written permission of ETSI. The content of the PDF version shall not be modified without the written authorization
8、of ETSI. The copyright and the foregoing restriction extend to reproduction in all media. ETSI 2018. All rights reserved. DECTTM, PLUGTESTSTM, UMTSTMand the ETSI logo are trademarks of ETSI registered for the benefit of its Members. 3GPPTM and LTETMare trademarks of ETSI registered for the benefit o
9、f its Members and of the 3GPP Organizational Partners. oneM2M logo is protected for the benefit of its Members. GSMand the GSM logo are trademarks registered and owned by the GSM Association. ETSI ETSI GS CIM 004 V1.1.1 (2018-04)3 Contents Intellectual Property Rights 10g3Foreword . 10g3Modal verbs
10、terminology 10g3Executive summary 10g3Introduction 10g31 Scope 12g32 References 12g32.1 Normative references . 12g32.2 Informative references 13g33 Definitions and abbreviations . 14g33.1 Definitions 14g33.2 Abbreviations . 15g34 Context Information Management Framework 16g34.1 Introduction 16g34.2
11、NGSI-LD Information Model. 16g34.2.1 Introduction. 16g34.2.2 NGSI-LD Meta Model 17g34.2.3 Cross Domain Ontology . 18g34.2.4 NGSI-LD domain-specific models and instantiation 18g34.2.5 UML representation 19g34.3 NGSI-LD Architectural considerations 20g34.3.1 Introduction. 20g34.3.2 Centralized archite
12、cture 20g34.3.3 Distributed architecture . 21g34.3.4 Federated architecture . 22g34.4 Core NGSI-LD context . 22g34.5 NGSI-LD Data Representation. 23g34.5.1 NGSI-LD Entity Representation . 23g34.5.2 NGSI-LD Property Representation . 23g34.5.3 NGSI-LD Relationship Representation 24g34.5.4 Simplified R
13、epresentation . 24g34.6 Data Representation Restrictions . 25g34.6.1 Supported text encodings 25g34.6.2 Supported names . 25g34.6.3 Supported data types for Values . 25g34.6.4 Supported Entity Content 26g34.7 Geospatial Properties 26g34.7.1 GeoJSON Geometries . 26g34.7.2 Representation of GeoJSON Ge
14、ometries in JSON-LD 27g34.8 Temporal properties . 27g34.9 NGSI-LD Query Language 28g34.10 NGSI-LD Geo-query language . 31g34.11 NGSI-LD Temporal Query language . 32g35 API Operation Definition . 33g35.1 Introduction 33g35.2 Data types . 33g35.2.1 Introduction. 33g35.2.2 Common members 34g35.2.3 cont
15、ext . 34g35.2.4 Entity 34g35.2.5 Property 35g35.2.6 Relationship 35g3ETSI ETSI GS CIM 004 V1.1.1 (2018-04)4 5.2.7 GeoProperty 35g35.2.8 EntityInfo 35g35.2.9 CsourceRegistration 36g35.2.10 RegistrationInfo 37g35.2.11 TimeInterval . 37g35.2.12 Subscription 37g35.2.13 GeoQuery 38g35.2.14 NotificationPa
16、rams . 39g35.2.14.1 NotificationParams data type definition 39g35.2.14.2 Additional members 39g35.2.15 EndPoint . 40g35.3 Notification data types 40g35.3.1 Notification . 40g35.3.2 CsourceNotification 41g35.3.3 TriggerReasonEnumeration 41g35.4 NGSI-LD Fragments 41g35.5 Common behaviours. 42g35.5.1 I
17、ntroduction. 42g35.5.2 Error types 42g35.5.3 Error payloads . 42g35.5.4 JSON-LD validation . 43g35.5.5 Default context assignment . 43g35.5.6 Operation execution 43g35.5.7 Term to URI expansion . 43g35.5.8 JSON-LD Merge Patch Behaviour . 43g35.6 Context Information Provision . 44g35.6.1 Create Entit
18、y . 44g35.6.1.1 Description 44g35.6.1.2 Use case diagram 44g35.6.1.3 Input data 44g35.6.1.4 Behaviour 44g35.6.1.5 Output data 44g35.6.2 Update Entity Attributes . 44g35.6.2.1 Description 44g35.6.2.2 Use case diagram 45g35.6.2.3 Input data 45g35.6.2.4 Behaviour 45g35.6.2.5 Output data 45g35.6.3 Appen
19、d Entity Attributes 45g35.6.3.1 Description 45g35.6.3.2 Use case diagram 45g35.6.3.3 Input data 46g35.6.3.4 Behaviour 46g35.6.3.5 Output data 46g35.6.4 Partial Attribute update . 47g35.6.4.1 Description 47g35.6.4.2 Use case diagram 47g35.6.4.3 Input data 47g35.6.4.4 Behaviour 47g35.6.4.5 Output data
20、 48g35.6.5 Delete Entity Attribute 48g35.6.5.1 Description 48g35.6.5.2 Use case diagram 48g35.6.5.3 Input data 48g35.6.5.4 Behaviour 48g35.6.5.5 Output data 49g35.6.6 Delete Entity . 49g35.6.6.1 Description 49g35.6.6.2 Use case diagram 49g35.6.6.3 Input data 49g35.6.6.4 Behaviour 49g35.6.6.5 Output
21、data 49g3ETSI ETSI GS CIM 004 V1.1.1 (2018-04)5 5.7 Context Information Consumption . 50g35.7.1 Retrieve Entity 50g35.7.1.1 Description 50g35.7.1.2 Use case diagram 50g35.7.1.3 Input data 50g35.7.1.4 Behaviour 50g35.7.1.5 Output data 50g35.7.2 Query Entities . 51g35.7.2.1 Description 51g35.7.2.2 Use
22、 case diagram 51g35.7.2.3 Input data 51g35.7.2.4 Behaviour 51g35.7.2.5 Output data 52g35.8 Context Information Subscription 52g35.8.1 Create Subscription . 52g35.8.1.1 Description 52g35.8.1.2 Use case diagram 52g35.8.1.3 Input data 52g35.8.1.4 Behaviour 53g35.8.1.5 Output data 53g35.8.2 Update Subsc
23、ription 53g35.8.2.1 Description 53g35.8.2.2 Use case diagram 53g35.8.2.3 Input data 54g35.8.2.4 Behaviour 54g35.8.2.5 Output data 54g35.8.3 Retrieve Subscription 54g35.8.3.1 Description 54g35.8.3.2 Use case diagram 54g35.8.3.3 Input data 55g35.8.3.4 Behaviour 55g35.8.3.5 Output data 55g35.8.4 Query
24、Subscriptions 55g35.8.4.1 Description 55g35.8.4.2 Use case diagram 55g35.8.4.3 Input data 56g35.8.4.4 Behaviour 56g35.8.4.5 Output data 56g35.8.5 Delete Subscription . 56g35.8.5.1 Description 56g35.8.5.2 Use case diagram 56g35.8.5.3 Input data 57g35.8.5.4 Behaviour 57g35.8.5.5 Output data 57g35.8.6
25、Notification behaviour 57g35.9 Context Source Registration . 58g35.9.1 Introduction. 58g35.9.2 Register Context Source . 58g35.9.2.1 Description 58g35.9.2.2 Use case diagram 58g35.9.2.3 Input data 59g35.9.2.4 Behaviour 59g35.9.2.5 Output data 60g35.9.3 Update Context Source Registration . 60g35.9.3.
26、1 Description 60g35.9.3.2 Use case diagram 60g35.9.3.3 Input data 60g35.9.3.4 Behaviour 60g35.9.3.5 Output data 61g35.9.4 Delete Context Source Registration 61g35.9.4.1 Description 61g35.9.4.2 Use case diagram 61g3ETSI ETSI GS CIM 004 V1.1.1 (2018-04)6 5.9.4.3 Input data 61g35.9.4.4 Behaviour 61g35.
27、9.4.5 Output data 61g35.10 Context Source Discovery 62g35.10.1 Retrieve Context Source Registration . 62g35.10.1.1 Description 62g35.10.1.2 Use case diagram 62g35.10.1.3 Input data 62g35.10.1.4 Behaviour 62g35.10.1.5 Output data 62g35.10.2 Query context source registrations 63g35.10.2.1 Description
28、63g35.10.2.2 Use case diagram 63g35.10.2.3 Input data 63g35.10.2.4 Behaviour 63g35.10.2.5 Output data 64g35.11 Context Source Registration Subscription 64g35.11.1 Introduction. 64g35.11.2 Create Context Source Registration Subscription . 64g35.11.2.1 Description 64g35.11.2.2 Use case diagram 64g35.1
29、1.2.3 Input data 65g35.11.2.4 Behaviour 65g35.11.2.5 Output data 65g35.11.3 Update context source discovery subscription 65g35.11.3.1 Description 65g35.11.3.2 Use case diagram 66g35.11.3.3 Input data 66g35.11.3.4 Behaviour 66g35.11.3.5 Output data 66g35.11.4 Retrieve context source discovery subscri
30、ption 66g35.11.4.1 Description 66g35.11.4.2 Use case diagram 67g35.11.4.3 Input data 67g35.11.4.4 Behaviour 67g35.11.4.5 Output data 67g35.11.5 Query Context Source Discovery subscriptions . 67g35.11.5.1 Description 67g35.11.5.2 Use case diagram 67g35.11.5.3 Input data 68g35.11.5.4 Behaviour 68g35.1
31、1.5.5 Output data 68g35.11.6 Delete context source discovery subscription . 68g35.11.6.1 Description 68g35.11.6.2 Use case diagram 68g35.11.6.3 Input data 69g35.11.6.4 Behaviour 69g35.11.6.5 Output data 69g35.11.7 Notification behaviour 69g35.12 Matching Context Source Registrations . 70g36 API HTTP
32、 binding . 71g36.1 Introduction 71g36.2 Global definitions and resource structure . 71g36.3 Common behaviours. 73g36.3.1 Introduction. 73g36.3.2 Error types 73g36.3.3 Reporting errors 74g36.3.4 HTTP request preconditions . 74g36.3.5 JSON-LD context resolution . 74g36.3.6 HTTP response common require
33、ments . 74g36.3.7 Simplified representation of entities . 75g3ETSI ETSI GS CIM 004 V1.1.1 (2018-04)7 6.3.8 Notification behaviour 75g36.3.9 Csource Notification behaviour 75g36.4 Resource: entities . 75g36.4.1 Description 75g36.4.2 Resource definition . 75g36.4.3 Resource methods . 75g36.4.3.1 POST
34、. 75g36.4.3.2 GET . 76g36.5 Resource: entities/entityId 77g36.5.1 Description 77g36.5.2 Resource definition . 78g36.5.3 Resource methods . 78g36.5.3.1 GET . 78g36.5.3.2 DELETE . 79g36.6 Resource: entities/entityId/attrs 79g36.6.1 Description 79g36.6.2 Resource definition . 79g36.6.3 Resource methods
35、 . 80g36.6.3.1 POST . 80g36.6.3.2 PATCH . 80g36.7 Resource: entities/entityId/attrs/attrId . 81g36.7.1 Description 81g36.7.2 Resource definition . 81g36.7.3 Resource methods . 82g36.7.3.1 PATCH . 82g36.7.3.2 DELETE . 82g36.8 Resource: csources . 83g36.8.1 Description 83g36.8.2 Resource definition .
36、83g36.8.3 Resource methods . 83g36.8.3.1 POST . 83g36.8.3.2 GET . 84g36.9 Resource: csources/registrationId . 86g36.9.1 Description 86g36.9.2 Resource definition . 86g36.9.3 Resource methods . 86g36.9.3.1 GET . 86g36.9.3.2 PATCH . 87g36.9.3.3 DELETE . 87g36.10 Resource: subscriptions 88g36.10.1 Desc
37、ription 88g36.10.2 Resource definition . 88g36.10.3 Resource methods . 88g36.10.3.1 POST . 88g36.10.3.2 GET . 89g36.11 Resource: subscriptions/subscriptionId 90g36.11.1 Description 90g36.11.2 Resource definition . 90g36.11.3 Resource methods . 90g36.11.3.1 GET . 90g36.11.3.2 PATCH . 91g36.11.3.3 DEL
38、ETE . 92g36.12 Resource: csourceSubscriptions . 92g36.12.1 Description 92g36.12.2 Resource definition . 93g36.12.3 Resource methods . 93g36.12.3.1 POST . 93g36.12.3.2 GET . 93g36.13 Resource: csourceSubscriptions/subscriptionId 94g36.13.1 Description 94g36.13.2 Resource definition . 94g36.13.3 Resou
39、rce methods . 95g3ETSI ETSI GS CIM 004 V1.1.1 (2018-04)8 6.13.3.1 GET . 95g36.13.3.2 PATCH . 95g36.13.3.3 DELETE . 96g3Annex A (normative): NGSI-LD identifier considerations 97g3A.1 Introduction 97g3A.2 Entity identifiers . 97g3A.3 NGSI-LD namespace . 97g3Annex B (normative): Core NGSI-LD context de
40、finition . 98g3Annex C (informative): Examples of using the API 100g3C.1 Introduction 100g3C.2 Entity Representation . 100g3C.2.1 Property Graph . 100g3C.2.2 Vehicle Entity . 101g3C.2.3 Parking Entity . 101g3C.2.4 context 102g3C.3 Context Source Registration . 103g3C.4 Context Subscription 104g3C.5
41、HTTP REST API Examples . 104g3C.5.1 Introduction 104g3C.5.2 Create Entity of Type Vehicle 104g3C.5.2.1 HTTP Request 104g3C.5.2.2 HTTP Response 104g3C.5.3 Query Entities . 105g3C.5.3.1 Introduction. 105g3C.5.3.2 HTTP Request 105g3C.5.3.3 HTTP Response 105g3Annex D (informative): Transformation Algori
42、thms 106g3D.1 Introduction 106g3D.2 Algorithm for transforming an NGSI-LD Entity into a JSON-LD document (ALG1) 106g3D.3 Algorithm for transforming a NGSI-LD Property into JSON-LD (ALG1.1) 107g3D.4 Algorithm for transforming a NGSI-LD Relationship into JSON-LD (ALG1.2) 108g3Annex E (informative): RD
43、F-compatible specification of NGSI-LD meta-model 109g3E.1 NGSI-LD Terms and categories: definitions 109g3E.2 Bridging Property graphs and RDF graphs 109g3E.3 Tentative formal definition of NGSI-LD information model . 110g3E.3.1 Introduction 110g3E.3.2 Core Meta-Model . 110g3E.3.3 Cross-Domain Meta-M
44、odel 110g3E.4 Example 112g3E.5 Complete Ontology in Turtle RDF Syntax . 113g3Annex F (informative): Gap analysis on the relationship of NGSI-LD and general triple-based queries 117g3Annex G (informative): Roadmap of Functionalities 119g3Annex H (informative): Open Issues . 121g3ETSI ETSI GS CIM 004
45、V1.1.1 (2018-04)9 Annex I (informative): Conventions and syntax guidelines. 123g3Annex J (informative): Authors 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
46、(https:/ipr.etsi.org/). Pursuant to the ETSI IPR Policy, no investigation, including IPR searches, has been carried out by ETSI. No guarantee can be given as to the existence of other IPRs not referenced in ETSI SR 000 314 (or the updates on the ETSI Web server) which are, or may be, or may become,
47、essential to the present document. Trademarks The present document may include trademarks and/or tradenames which are asserted and/or registered by their owners. ETSI claims no ownership of these except for any which are indicated as being the property of ETSI, and conveys no right to use or reprodu
48、ce any trademark and/or tradename. Mention of those trademarks in the present document does not constitute an endorsement by ETSI of products, services or organizations associated with those trademarks. Foreword This Group Specification (GS) has been produced by ETSI Industry Specification Group (IS
49、G) 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 Specification (preliminary). The Contex
